Quarkus - 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 during build by default. This optimization can be disabled by setting quarkus.arc.remove-unused-beans to none or false.

An unused bean:

This optimization applies to all forms of bean declarations: bean class, producer method, producer field.

Users can instruct the container to not remove any of their specific beans (even if they satisfy all the rules specified above) by annotating them with io.quarkus.arc.Unremovable. This annotation can be placed on the types, producer methods, and producer fields.

Since this is not always possible, there is an option to achieve the same via application.properties. The quarkus.arc.unremovable-types property accepts a list of string values that are used to match beans based on their name or package.

Furthermore, extensions can eliminate possible false positives by producing UnremovableBeanBuildItem.

Finally, Quarkus provides a middle ground for the bean removal optimization 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.

When using the dev mode (running ./mvnw clean compile quarkus:dev), you can see more information about which beans are being removed by enabling additional logging via the following line in your application.properties.

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 a specific value, via the @io.quarkus.arc.properties.IfBuildProperty annotation. 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:

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 @Priority is that it has @Target({ TYPE, PARAMETER }) and so it cannot be used for producer methods and fields. To address this problem and to simplify the code Quarkus provides the io.quarkus.arc.AlternativePriority annotation. It’s basically a shortcut for @Alternative plus @Priority. Additionally, it can be used for producers.

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 incorporates build-time optimizations in order to provide instant startup and low memory footprint. The downside of this approach is that CDI Portable Extensions cannot be supported. Nevertheless, most of the functionality can be achieved using Quarkus extensions.

As described in Bean Discovery bean classes that don’t have a bean defining annotation are not discovered. However, BeanDefiningAnnotationBuildItem can be used to extend the set of default bean defining annotations (@Dependent, @Singleton, @ApplicationScoped, @RequestScoped and @Stereotype annotations):

ResourceAnnotationBuildItem is used to specify resource annotations that make it possible to resolve non-CDI injection points, such as Java EE resources.

AdditionalBeanBuildItem is used to specify additional bean classes to be analyzed during discovery. Additional bean classes are transparently added to the application index processed by the container.

Sometimes it is very useful to be able to register a synthetic bean. Bean attributes of a synthetic bean are not derived from a java class, method or field. Instead, the attributes are specified by an extension. In CDI, this could be achieved using the AfterBeanDiscovery.addBean() methods. In Quarkus, there are three ways to register a synthetic bean.

A very common task is to override the annotations found on the bean classes. For example you might want to add an interceptor binding to a specific bean class. Here is how to do it - use the AnnotationsTransformerBuildItem:

In rare cases it might be handy to programmatically register an existing annotation as interceptor binding. This is similar to what pure CDI achieves through BeforeBeanDiscovery#addInterceptorBinding(). Though here we are going to use InterceptorBindingRegistrarBuildItem to get it done. Note that you can register multiple annotations in one go:

Every now and then it is handy to be able to change qualifiers of an injection point programmatically. You can do just that with InjectionPointTransformerBuildItem. The following sample shows how to apply transformation to injection points with type Foo that contain qualifier MyQualifier:

Any observer method definition can be vetoed or transformed using an ObserverTransformerBuildItem. The attributes that can be transformed include:

Once the bean deployment is ready an extension can perform additional validations and inspect the found beans, observers and injection points. Register a BeanDeploymentValidatorBuildItem:

If an extension needs to produce other build items during the "validation" phase it should use the ValidationPhaseBuildItem instead. The reason is that injected objects are only valid during a @BuildStep method invocation.

An extension can register a custom InjectableContext implementation by means of a ContextRegistrarBuildItem:

If an extension needs to produce other build items during the "context registration" phase it should use the ContextRegistrationPhaseBuildItem instead. The reason is that injected objects are only valid during a @BuildStep method invocation.

Any of the above extensions that operates with BuildExtension.BuildContext can leverage certain build time metadata that are generated during build. The built-in keys located in io.quarkus.arc.processor.BuildExtension.Key are:

To get hold of these, simply query the extension context object for given key. Note that these metadata are made available as build proceeds which means that extensions can only leverage metadata that were build before they are invoked. If your extension attempts to retrieve metadata that wasn’t yet produced, null will be returned. Here is a summary of which extensions can access which metadata: