Quarkus - Introduction to Contexts and Dependency Injection

In this guide we’re going to describe the basic principles of the Quarkus programming model that is based on the Contexts and Dependency Injection for Java 2.0 specification.

1. Q: OK. Let’s start simple. What is a bean?

A: Well, a bean is a container-managed object that supports a set of basic services, such as injection of dependencies, lifecycle callbacks and interceptors.

2. Q: Wait a minute. What does “container-managed” mean?

A: Simply put, you don’t control the lifecycle of the object instance directly. Instead, you can affect the lifecycle through declarative means, such as annotations, configuration, etc. The container is the environment where your application runs. It creates and destroys the instances of beans, associates the instances with a designated context, and injects them into other beans.

3. Q: What is it good for?

A: An application developer can focus on the business logic rather than finding out “where and how” to obtain a fully initialized component with all of its dependencies.

4. Q: What does a bean look like?

A: There are several kinds of beans. The most common ones are class-based beans:

Simple Bean Example

import javax.inject.Inject;
import javax.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.metrics.annotation.Counted;
@ApplicationScoped (1)
public class Translator {
    @Inject
    Dictionary dictionary; (2)
    @Counted  (3)
    String translate(String sentence) {
      // ...
    }
}

5. Q: Nice. How does the dependency resolution work? I see no names or identifiers.

A: That’s a good question. In CDI the process of matching a bean to an injection point is type-safe. Each bean declares a set of bean types. In our example above, the Translator bean has two bean types: Translator and java.lang.Object. Subsequently, a bean is assignable to an injection point if the bean has a bean type that matches the required type and has all the required qualifiers. We’ll talk about qualifiers later. For now, it’s enough to know that the bean above is assignable to an injection point of type Translator and java.lang.Object.

6. Q: Hm, wait a minute. What happens if multiple beans declare the same type?

A: There is a simple rule: exactly one bean must be assignable to an injection point, otherwise the build fails. If none is assignable the build fails with UnsatisfiedResolutionException. If multiple are assignable the build fails with AmbiguousResolutionException. This is very useful because your application fails fast whenever the container is not able to find an unambiguous dependency for any injection point.

public class Translator {
    @Inject
    Instance<Dictionary> dictionaries; (1)
    String translate(String sentence) {
      for (Dictionary dict : dictionaries) { (2)
         // …
      }
    }
}

7. Q: Can I use setter and constructor injection?

A: Yes, you can. In fact, in CDI the “setter injection” is superseded by more powerful initializer methods. Intializers may accept multiple parameters and don’t have to follow the JavaBean naming conventions.

Initialized and Constructor Injection Example

@ApplicationScoped
public class Translator {
    private final TranslatorHelper helper
    Translator(TranslatorHelper helper) { (1)
       this.helper = helper;
    }
    @Inject (2)
    void setDeps(Dictionary dic, LocalizationService locService) { (3)
      / ...
    }
}

8. Q: You talked about some qualifiers?

A: Qualifiers are annotations that help the container to distinguish beans that implement the same type. As we already said a bean is assignable to an injection point if it has all the required qualifiers. If you declare no qualifier at an injection point the @Default qualifier is assumed.

A qualifier type is a Java annotation defined as @Retention(RUNTIME) and annotated with the @javax.inject.Qualifier meta-annotation:

Qualifier Example

@Qualifier
@Retention(RUNTIME)
@Target({METHOD, FIELD, PARAMETER, TYPE})
public @interface Superior {}

The qualifiers of a bean are declared by annotating the bean class or producer method or field with the qualifier types:

Bean With Custom Qualifier Example

@Superior (1)
@ApplicationScoped
public class SuperiorTranslator extends Translator {
    String translate(String sentence) {
      // ...
    }
}

This bean would be assignable to @Inject @Superior Translator and @Inject @Superior SuperiorTranslator but not to @Inject Translator. The reason is that @Inject Translator is automatically transformed to @Inject @Default Translator during typesafe resolution. And since our SuperiorTranslator does not declare @Default only the original Translator bean is assignable.

9. Q: Looks good. What is the bean scope?

The scope of a bean determines the lifecycle of its instances, i.e. when and where an instance should be created and destroyed.

10. Q: What scopes can I actually use in my Quarkus application?

A: You can use all the built-in scopes mentioned by the specification except for javax.enterprise.context.ConversationScoped.

11. Q: I don’t undestand the concept of client proxies.

Indeed, the client proxies could be hard to grasp but they provide some useful functionality. A client proxy is basically an object that delegates all method invocations to a target bean instance. It’s a container construct that implements io.quarkus.arc.ClientProxy and extends the bean class.

Generated Client Proxy Example

@ApplicationScoped
class Translator {
    String translate(String sentence) {
      // ...
    }
}
// The client proxy class is generated and looks like...
class Translator_ClientProxy extends Translator { (1)
    String translate(String sentence) {
      // Find the correct translator instance...
      Translator translator = getTranslatorInstanceFromTheApplicationContext();
      // And delegate the method invocation...
      return translator.translate(sentence);
    }
}

Client proxies allow for:

• Lazy instantiation - the instance is created once a method is invoked upon the proxy.

• Ability to inject a bean with “narrower” scope to a bean with “wider” scope; i.e. you can inject a @RequestScoped bean into an @ApplicationScoped bean.

• Circular dependencies in the dependency graph. Having circular dependencies is often an indication that a redesign should be considered, but sometimes it’s inevitable.

• In rare cases it’s practical to destroy the beans manually. A direct injected reference would lead to a stale bean instance.

12. Q: OK. You said that there are several kinds of beans?

A: Yes. In general, we distinguish:

1. Class beans

2. Producer methods

3. Producer fields

4. Synthetic beans

Producer methods and fields are useful if you need additional control over instantiation of a bean. They are also useful when integrating third-party libraries where you don’t control the class source and may not add additional annotations etc.

Producers Example

@ApplicationScoped
public class Producers {
    @Produces (1)
    double pi = Math.PI; (2)
    @Produces (3)
    List<String> names() {
       List<String> names = new ArrayList<>();
       names.add("Andy");
       names.add("Adalbert");
       names.add("Joachim");
       return names; (4)
    }
}
@ApplicationScoped
public class Consumer {
   @Inject
   double pi;
   @Inject
   List<String> names;
   // ...
}

There’s more about producers. You can declare qualifiers, inject dependencies into the producer methods parameters, etc. You can read more about producers for example in the Weld docs.

13. Q: OK, injection looks cool. What other services are provided?

13.1. Lifecycle Callbacks

A bean class may declare lifecycle @PostConstruct and @PreDestroy callbacks:

Lifecycle Callbacks Example

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
@ApplicationScoped
public class Translator {
    @PostConstruct (1)
    void init() {
       // ...
    }
    @PreDestroy (2)
    void destroy() {
      // ...
    }
}

13.2. Interceptors

Interceptors are used to separate cross-cutting concerns from business logic. There is a separate specification - Java Interceptors - that defines the basic programming model and semantics.

Simple Interceptor Example

import javax.interceptor.Interceptor;
import javax.annotation.Priority;
@Logged (1)
@Priority(2020) (2)
@Interceptor (3)
public class LoggingInterceptor {
   @Inject (4)
   Logger logger;
   @AroundInvoke (5)
   Objec logInvocation(InvocationContext context) {
      // ...log before
      Objec ret = context.proceed(); (6)
      // ...log after
      return ret;
   }
}

13.3. Events and Observers

Beans may also produce and consume events to interact in a completely decoupled fashion. Any Java object can serve as an event payload. The optional qualifiers act as topic selectors.

Simple Event Example

class TaskCompleted {
  // ...
}
@ApplicationScoped
class ComplicatedService {
   @Inject
   Event<Task> event; (1)
   void doSomething() {
      // ...
      event.fire(new TaskCompleted()); (2)
   }
}
@ApplicationScoped
class Logger {
   void onTaskCompleted(@Observes TaskCompleted task) { (3)
      // ...log the task
   }
}

14. Conclusion

In this guide, we’ve covered some of the basic topics of the Quarkus programming model that is based on the Contexts and Dependency Injection for Java 2.0 specification. However, a full CDI implementation is not used under the hood. Quarkus only implements a subset of the CDI features - see also the list of supported features and the list of limitations. On the other hand, there are quite a few non-standard features and Quarkus-specific APIs. We believe that our efforts will drive the innovation of the CDI specification towards the build-time oriented developer stacks in the future.