Contexts and Dependency Injection

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

If you are are using gradle, you can apply the following plugin to your build.gradle:

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.

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 auto-configures 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.

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 be do nothing when in tests or 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/has not 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, this annotation 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.

The disadvantage of @javax.annotation.Priority is that it has @Target({ TYPE, PARAMETER }) and so it cannot be used for producer methods and fields. This problem should be fixed in Common Annotations 2.1. Users are encouraged to use @io.quarkus.arc.Priority instead, until Quarkus upgrades to this version of jakarta.annotation-api.

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 @AlternativePriority 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 javax.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 javax.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.

In CDI, it’s possible to inject multiple bean instances (aka contextual references) via the javax.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 @javax.inject.Singleton or @javax.enterprise.context.ApplicationScoped.