Contexts and Dependency Injection

A dependency with a Jandex index is automatically scanned for beans. To generate the index just add the following plugin to your build file:

If you can’t modify the dependency, you can still index it by adding quarkus.index-dependency entries to your application.properties:

For example, the following entries ensure that the org.acme:acme-api dependency is indexed:

It may happen that some beans from third-party libraries do not work correctly in Quarkus. A typical example is a bean injecting a portable extension. In such case, it’s possible to exclude types and dependencies from the bean discovery. The quarkus.arc.exclude-types property accepts a list of string values that are used to match classes that should be excluded.

It is also possible to exclude a dependency artifact that would be otherwise scanned for beans. For example, because it contains a beans.xml descriptor.

There is one case where @Named is the right thing to use: specifying an external identifier for a different language that doesn’t support dependency injection directly.

For example:

As you can see, in the application code, the bean is injected without a qualifier. The bean name is only used to refer to the bean in the other language.

Historically, the most common external language that used bean names was JSF. In Quarkus, we have Qute. In a Qute template, one would refer to the bean using its name:

Outside of this use-case, just use @Identifier.

The request context is also active:

The request context is destroyed:

In CDI, if you declare a field injection point you need to use @Inject and optionally a set of qualifiers.

In Quarkus, you can skip the @Inject annotation completely if the injected field declares at least one qualifier.

In CDI, a normal scoped bean must always declare a no-args constructor (this constructor is normally generated by the compiler unless you declare any other constructor). However, this requirement complicates constructor injection - you need to provide a dummy no-args constructor to make things work in CDI.

There is no need to declare dummy constructors for normal scoped bean in Quarkus - they are generated automatically. Also, if there’s only one constructor there is no need for @Inject.

The container attempts to remove all unused beans, interceptors and decorators during build by default. This optimization helps to minimize the amount of generated classes, thus conserving memory. However, Quarkus can’t detect the programmatic lookup performed via the CDI.current() static method. Therefore, it is possible that a removal results in a false positive error, i.e. a bean is removed although it’s actually used. In such cases, you’ll notice a big warning in the log. Users and extension authors have several options how to eliminate false positives.

The optimization can be disabled by setting quarkus.arc.remove-unused-beans to none or false. Quarkus also provides a middle ground where application beans are never removed whether or not they are unused, while the optimization proceeds normally for non application classes. To use this mode, set quarkus.arc.remove-unused-beans to fwk or framework.

Quarkus adds a capability that CDI currently does not support which is to conditionally declare a bean if no other bean with equal types and qualifiers was declared by any available means (bean class, producer, synthetic bean, …​) This is done using the @io.quarkus.arc.DefaultBean annotation and is best explained with an example.

Say there is a Quarkus extension that among other things declares a few CDI beans like the following code does:

The idea is that the extension autoconfigures things for the user, eliminating a lot of boilerplate - we can just @Inject a Tracer wherever it is needed. Now imagine that in our application we would like to utilize the configured Tracer, but we need to customize it a little, for example by providing a custom Reporter. The only thing that would be needed in our application would be something like the following:

@DefaultBean allows extensions (or any other code for that matter) to provide defaults while backing off if beans of that type are supplied in any way Quarkus supports.

Default beans can optionally declare @jakarta.annotation.Priority. If there is no priority defined, @Priority(0) is assumed. Priority value is used for bean ordering and during typesafe resolution to disambiguate multiple matching default beans.

Quarkus adds a capability that CDI currently does not support which is to conditionally enable a bean when a Quarkus build time profile is enabled, via the @io.quarkus.arc.profile.IfBuildProfile and @io.quarkus.arc.profile.UnlessBuildProfile annotations. When used in conjunction with @io.quarkus.arc.DefaultBean, these annotations allow for the creation of different bean configurations for different build profiles.

Imagine for instance that an application contains a bean named Tracer, which needs to do nothing when in tests or in dev mode, but works in its normal capacity for the production artifact. An elegant way to create such beans is the following:

If instead, it is required that the Tracer bean also works in dev mode and only default to doing nothing for tests, then @UnlessBuildProfile would be ideal. The code would look like:

Quarkus adds a capability that CDI currently does not support which is to conditionally enable a bean when a Quarkus build time property has or does not have a specific value, via the @io.quarkus.arc.properties.IfBuildProperty and @io.quarkus.arc.properties.UnlessBuildProperty annotations. When used in conjunction with @io.quarkus.arc.DefaultBean, these annotations allow for the creation of different bean configurations for different build properties.

The scenario we mentioned above with Tracer could also be implemented in the following way:

If instead, it is required that the RealTracer bean is only used if the some.tracer.enabled property is not false, then @UnlessBuildProperty would be ideal. The code would look like:

In CDI, an alternative bean may be selected either globally for an application by means of @Priority, or for a bean archive using a beans.xml descriptor. Quarkus has a simplified bean discovery and the content of beans.xml is ignored.

However, it is also possible to select alternatives for an application using the unified configuration. The quarkus.arc.selected-alternatives property accepts a list of string values that are used to match alternative beans. If any value matches then the priority of Integer#MAX_VALUE is used for the relevant bean. The priority declared via @Priority or inherited from a stereotype is overridden.

In CDI, a producer method must be always annotated with @Produces.

In Quarkus, you can skip the @Produces annotation completely if the producer method is annotated with a scope annotation, a stereotype or a qualifier.

The Interceptors specification is clear that around-invoke methods must not be declared static. However, this restriction was driven mostly by technical limitations. And since Quarkus is a build-time oriented stack that allows for additional class transformations, those limitations don’t apply anymore. It’s possible to annotate a non-private static method with an interceptor binding:

In normal CDI, classes that are marked as final and / or have final methods are not eligible for proxy creation, which in turn means that interceptors and normal scoped beans don’t work properly. This situation is very common when trying to use CDI with alternative JVM languages like Kotlin where classes and methods are final by default.

Quarkus however, can overcome these limitations when quarkus.arc.transform-unproxyable-classes is set to true (which is the default value).

There is no standard concurrency control mechanism for CDI beans. Nevertheless, a bean instance can be shared and accessed concurrently from multiple threads. In that case it should be thread-safe. You can use standard Java constructs (volatile, synchronized, ReadWriteLock, etc.) or let the container control the concurrent access. Quarkus provides @io.quarkus.arc.Lock and a built-in interceptor for this interceptor binding. Each interceptor instance associated with a contextual instance of an intercepted bean holds a separate ReadWriteLock with non-fair ordering policy.

Quarkus has limited support for @Repeatable interceptor binding annotations.

When binding an interceptor to a component, you can declare multiple @Repeatable annotations on methods. Repeatable interceptor bindings declared on classes and stereotypes are not supported, because there are some open questions around interactions with the Interceptors specification. This might be added in the future.

As an example, suppose we have an interceptor that clears a cache. The corresponding interceptor binding would be called @CacheInvalidateAll and would be declared as @Repeatable. If we wanted to clear two caches at the same time, we would add @CacheInvalidateAll twice:

This is how interceptors are used. What about creating an interceptor?

When declaring interceptor bindings of an interceptor, you can add multiple @Repeatable annotations to the interceptor class as usual. This is useless when the annotation members are @Nonbinding, as would be the case for the @Cached annotation, but is important otherwise.

For example, suppose we have an interceptor that can automatically log method invocations to certain targets. The interceptor binding annotation @Logged would have a member called target, which specifies where to store the log. Our implementation could be restricted to console logging and file logging:

Other interceptors could be provided to log method invocations to different targets.

In certain situations, it is practical to obtain a bean instance programmatically via an injected jakarta.enterprise.inject.Instance and Instance.get(). However, according to the specification the get() method must identify the matching bean and obtain a contextual reference. As a consequence, a new instance of a @Dependent bean is returned from each invocation of get(). Moreover, this instance is a dependent object of the injected Instance. This behavior is well-defined, but it may lead to unexpected errors and memory leaks. Therefore, Quarkus comes with the io.quarkus.arc.WithCaching annotation. An injected Instance annotated with this annotation will cache the result of the Instance#get() operation. The result is computed on the first call and the same value is returned for all subsequent calls, even for @Dependent beans.

It is sometimes useful to narrow down the set of beans that can be obtained by programmatic lookup via jakarta.enterprise.inject.Instance. Typically, a user needs to choose the appropriate implementation of an interface based on a runtime configuration property.

Imagine that we have two beans implementing the interface org.acme.Service. You can’t inject the org.acme.Service directly unless your implementations declare a CDI qualifier. However, you can inject the Instance<Service> instead, then iterate over all implementations and choose the correct one manually. Alternatively, you can use the @LookupIfProperty and @LookupUnlessProperty annotations. @LookupIfProperty indicates that a bean should only be obtained if a runtime configuration property matches the provided value. @LookupUnlessProperty, on the other hand, indicates that a bean should only be obtained if a runtime configuration property does not match the provided value.

If there is more than one bean that matches the required type and qualifiers and is eligible for injection, it is possible to iterate (or stream) available bean instances. Beans returned by both stream and iterator methods are sorted by priority as defined by io.quarkus.arc.InjectableBean#getPriority(). Higher priority goes first. If no priority is explicitly declared, 0 is assumed.

In CDI, it’s possible to inject multiple bean instances (aka contextual references) via the jakarta.enterprise.inject.Instance which implements java.lang.Iterable. However, it’s not exactly intuitive. Therefore, a new way was introduced in Quarkus - you can inject a java.util.List annotated with the io.quarkus.arc.All qualifier. The type of elements in the list is used as the required type when performing the lookup.

If an injection point declares no other qualifier than @All then @Any is used, i.e. the behavior is equivalent to @Inject @Any Instance<Service>.

You can also inject a list of bean instances wrapped in io.quarkus.arc.InstanceHandle. This can be useful if you need to inspect the related bean metadata.

If a managed bean declares interceptor binding annotations on the class level, the corresponding @AroundInvoke interceptors will apply to all business methods. Similarly, the corresponding @AroundConstruct interceptors will apply to the bean constructor.

For example, suppose we have a logging interceptor with the @Logged binding annotation and a tracing interceptor with the @Traced binding annotation:

In this example, both doSomething and doSomethingElse will be intercepted by the hypothetical logging interceptor. Additionally, the doSomethingElse method will be intercepted by the hypothetical tracing interceptor.

Now, if that @Traced interceptor also performed all the necessary logging, we’d like to skip the @Logged interceptor for this method, but keep it for all other methods. To achieve that, you can annotate the method with @NoClassInterceptors:

The @NoClassInterceptors annotation may be put on methods and constructors and means that all class-level interceptors are ignored for these methods and constructors. In other words, if a method/constructor is annotated @NoClassInterceptors, then the only interceptors that will apply to this method/constructor are interceptors declared directly on the method/constructor.

This annotation affects only business method interceptors (@AroundInvoke) and constructor lifecycle callback interceptors (@AroundConstruct).

If an exception is thrown by an asynchronous observer then the CompletionStage returned by the fireAsync() method completes exceptionally so that the event producer may react appropriately. However, if the event producer does not care then the exception is ignored silently. Therefore, Quarkus logs an error message by default. It is also possible to implement a custom AsyncObserverExceptionHandler. A bean that implements this interface should be @jakarta.inject.Singleton or @jakarta.enterprise.context.ApplicationScoped.

Quarkus supports what is known as intercepted self-invocation or just self-interception - a scenario where CDI bean invokes its own intercepted method from within another method while triggering any associated interceptors. This is a non-standard feature as CDI specification doesn’t define whether self-interception should work or not.

Suppose we have a CDI bean with two methods, one of which has the @Transactional interceptor binding associated with it:

In the above example, any code calling the doSomething() method triggers interception - in this case, the method becomes transactional. This is regardless of whether the invocation originated directly from the MyService bean (such as MyService#doSomethingElse) or from some other bean.

By default, interception is only supported for managed beans (also known as class-based beans). To support interception of producer methods and synthetic beans, the CDI specification includes an InterceptionFactory, which is a runtime oriented concept and therefore cannot be supported in Quarkus.

Instead, Quarkus has its own API: InterceptionProxy and @BindingsSource. The InterceptionProxy is very similar to InterceptionFactory: it creates a proxy that applies @AroundInvoke interceptors before forwarding the method call to the target instance. The @BindingsSource annotation allows setting interceptor bindings in case the intercepted class is external and cannot be changed.

In this example, interceptor bindings are read from the MyClass class.

The intercepted class should be proxyable and therefore should not be final, should not have non-private final methods, and should have a non-private zero-parameter constructor. If it isn’t, a bytecode transformation will attempt to fix it if enabled, but note that adding a zero-parameter constructor is not always possible.

It is often the case that the produced classes come from external libraries and don’t contain interceptor binding annotations at all. To support such cases, the @BindingsSource annotation may be declared on the InterceptionProxy parameter:

The concept of bindings source is a build-time friendly equivalent of InterceptionFactory.configure().

Per the CDI specification, the Instance.Handle.close() method always delegates to destroy(). In ArC, this is only true in the Strict Mode.

In the default mode, the close() method only delegates to destroy() when the bean is @Dependent (or when the instance handle does not represent a CDI contextual object). When the instance handle represents a bean of any other scope, the close() method does nothing; the bean is left as is and will be destroyed whenever its context is destroyed.

This is to make the following code behave as one would naively expect:

The @Dependent beans are destroyed immediately, while other beans are not destroyed at all. This is important when multiple beans of different scopes might be returned by the Instance.

The io.quarkus.runtime.BlockingOperationControl#isBlockingAllowed() method can be used to detect whether blocking is allowed on the current thread. When it is not, and you need to perform a blocking operation, you have to offload it to another thread. The easiest way is to use the Vertx.executeBlocking() method:

CDI asynchronous observers (@ObservesAsync) are not aware of reactive programming and are not meant to be used as part of reactive pipelines. The observer methods are meant to be synchronous, they are just offloaded to a thread pool.

The Event.fireAsync() method returns a CompletionStage that completes when all observers are notified. If all observers were notified successfully, the CompletionStage completes with the event payload. If some observers have thrown an exception, the CompletionStage completes exceptionally with a CompletionException.

The return type of the observer does not matter. The return value of the observer is ignored.

You may declare an observer method that has a return type of CompletionStage<> or Uni<>, but neither the return type nor the actual return value affect the result of Event.fireAsync(). Further, if the observer declares a return type of Uni<>, the returned Uni will not be subscribed to, so it is quite possible that part of the observer logic will not even execute.

Therefore, it is recommended that observer methods, both synchronous and asynchronous, are always declared void.

In dev mode, it is also possible to enable monitoring of business method invocations and fired events. Simply set the quarkus.arc.dev-mode.monitoring-enabled configuration property to true and explore the relevant Dev UI pages.