Quarkus Bean Discovery With Jandex Indexing

1. Overview

In this article, we’ll learn the difference between bean discovery in Quarkus and classic Jakarta EE environments. We’ll focus on how to ensure that Quarkus can discover annotated classes in external modules.

2. Why Quarkus Needs Indexing

One of the main advantages of Quarkus is its extremely fast boot time. To achieve this, Quarkus moves steps like classpath annotation scanning forward from runtime to build-time. For this, we need to announce all dependencies at build-time.

So, enhancing an application by classpath extension at the runtime environment is not possible anymore. Indexing joins the game when metadata is collected during the build. Indexing means storing metadata within an index file. This allows the application to read it out quickly at startup or whenever it’s needed.

Let’s examine the difference using a simple sketch:

Quarkus uses Jandex to create and read the index.

3. Create an Index

For the classes in our Quarkus project, we don’t have to do anything special – the Quarkus Maven Plugin will generate the index automatically. But, we need to pay attention to the dependencies – the project-internal modules as well as the external libraries.

3.1. Jandex Maven Plugin

The most obvious method to achieve this for our own modules is to use the Jandex Maven Plugin:

<build>
    <plugins>
        <plugin>
            <!-- https://github.com/wildfly/jandex-maven-plugin -->
            <groupId>org.jboss.jandex</groupId>
            <artifactId>jandex-maven-plugin</artifactId>
            <version>1.2.1</version>
            <executions>
                <execution>
                    <id>make-index</id>
                    <goals>
                        <!-- phase is 'process-classes by default' -->
                        <goal>jandex</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

This plugin creates a “META-INF/jandex.idx” file packaged into the JAR. Quarkus will read out this file when provided by the library at runtime. So, each library that contains such a file implicitly enhances the index.

For Gradle builds, we can use the org.kordamp.gradle.jandex plugin:

plugins {
    id 'org.kordamp.gradle.jandex' version '0.11.0'
}

3.2. Application Properties

If we cannot modify the dependencies (for example, in the case of external libraries), we need to specify them explicitly in the Quarkus project’s application.properties file:

quarkus.index-dependency.<name>.group-id=<groupId>
quarkus.index-dependency.<name>.artifact-id=<artifactId>
quarkus.index-dependency.<name>.classifier=(optional)

3.3. Framework-Specified Implications

Instead of using the Jandex Maven Plugin, a module could also contain a META-INF/beans.xml file. This is actually part of the CDI technology that is adopted into Quarkus with some adjustments, but we are not restricted to using CDI-managed beans only. We could also declare, for example, JAX-RS resources because the scope of the index is the whole module.

4. Conclusion

This article has determined that Quarkus needs a Jandex index to detect annotated classes at runtime. The index is generated during build time, so the standard technologies do not detect annotated classes added to the classpath after the build.