Quarkus - Writing Your Own Extension

Let us assume that the Quarkus extension needs to provide a Tracer bean which application code is meant to inject into its own beans.

If for example application code wants to use Tracer, but also needs to use a custom Reporter bean, such a requirement could easily be done using something like:

Although @DefaultBean is the recommended approach, it is also possible for application code to override beans provided by an extension by marking beans as a CDI @Alternative and including @Priority annotation. Let’s show a simple example. Suppose we work on an imaginary "quarkus-parser" extension and we have a default bean implementation:

And our extension also consumes this parser:

Now, if a user or even some other extension needs to override the default implementation of the Parser the simplest solution is to use CDI @Alternative + @Priority:

The create-extension mojo of io.quarkus:quarkus-maven-plugin can be used to generate stubs of Maven modules needed for implementing a new Quarkus extension.

As and example, let’s add a new extension called my-ext to the Quarkus source tree:

The above sequence of commands does the following:

A Maven build performed immediately after generating the modules should fail due to a fail() assertion in one of the test classes.

There is one step (specific to the Quarkus source tree) that you should do manually when creating a new extension: create a quarkus-extension.yaml file that describe your extension inside the runtime module src/main/resources/META-INF folder.

This is the quarkus-extension.yaml of the quarkus-agroal extension, you can use it as an example:

Note that the parameters of the mojo that will be constant for all the extensions added to this source tree are configured in extensions/pom.xml so that they do not need to be passed on the command line each time a new extension is added:

Please refer to CreateExtensionMojo JavaDoc for all the available options of the mojo.

A build step is a method which is annotated with the @io.quarkus.deployment.annotations.BuildStep annotation. Each build step may consume items that are produced by earlier stages, and produce items that can be consumed by later stages. Build steps are normally only run when they produce a build item that is ultimately consumed by another step.

Build steps are normally placed on plain classes within an extension’s deployment module. The classes are automatically instantiated during the augment process and utilize injection.

Build items are concrete, final subclasses of the abstract io.quarkus.builder.item.BuildItem class. Each build item represents some unit of information that must be passed from one stage to another. The base BuildItem class may not itself be directly subclassed; rather, there are abstract subclasses for each of the kinds of build item subclasses that may be created: simple, multi, and empty.

Think of build items as a way for different extensions to communicate with one another. For example, a build item can:

This is a very flexible mechanism.

Classes which contain build steps support the following types of injection:

Build step classes are instantiated and injected for each build step invocation, and are discarded afterwards. State should only be communicated between build steps by way of build items, even if the steps are on the same class.

The types of values that can be injected include:

A build step may produce values for subsequent steps in several possible ways:

If a simple build item is declared on a build step, it must be produced during that build step, otherwise an error will result. Build producers which are injected into steps must not be used outside of that step.

Note that a @BuildStep method will only be called if it produces something that another consumer or the final output requires. If there is no consumer for a particular item then it will not be produced. What is required will depend on the final target that is being produced. For example, when running in developer mode the final output will not ask for GraalVM-specific build items such as ReflectiveClassBuildItem, so methods that only produce these items will not be invoked.

A build step may consume values from previous steps in the following ways:

Normally it is an error for a step which is included to consume a simple build item that is not produced by any other step. In this way, it is guaranteed that all of the declared values will be present and non-null when a step is run.

Sometimes a value isn’t necessary for the build to complete, but might inform some behavior of the build step if it is present. In this case, the value can be optionally injected.

The @BuildStep annotation has a providesCapabilities property that can be used to provide capability information to other extensions about what is present in the current application. Capabilities are simply strings that are used to describe an extension. Capabilities should generally be named after an extensions root package, for example the transactions extension will provide io.quarkus.transactions.

To check if a capability is present you can inject the io.quarkus.deployment.Capabilities object and call isCapabilityPresent.

Capabilities should be used when checking for the presence of an extension rather than class path based checks.

The @BuildStep annotation can also register marker files that determine which archives on the class path are considered to be 'Application Archives', and will therefore get indexed. This is done via the applicationArchiveMarkers. For example the ArC extension registers META-INF/beans.xml, which means that all archives on the class path with a beans.xml file will be indexed.

If @BuildStep.loadsApplicationClasses() is set to true the build step will be run with a TCCL that can load user classes from the deployment in a transformer-safe way. This class loader only lasts for the life of the augmentation, and is discarded afterwards. The classes will be loaded again in a different class loader at runtime. This means that loading a class during augmentation does not stop it from being transformed when running in the development/test mode.

Leaf configuration keys are mapped to non-private fields via the @io.quarkus.runtime.annotations.ConfigItem annotation.

Configuration keys are normally derived from the field names that they are tied to. This is done by de-camel-casing the name and then joining the segments with hyphens (-). Some examples:

The name can also be explicitly specified by giving a name attribute to the @ConfigItem annotation.

The type of the field with the @ConfigItem annotation determines the conversion that is applied to it. Quarkus extensions may use the full range of configuration types made available by SmallRye Config, which includes:

In addition, custom converters may be registered by adding their fully qualified class name in file META-INF/services/org.eclipse.microprofile.config.spi.Converter.

Though these implicit converters use reflection, Quarkus will automatically ensure that they are loaded at the appropriate time.

A configuration item can be marked to have a default value. The default value is used when no matching configuration key is specified in the configuration.

Configuration items with a primitive type (such as int or boolean) implicitly use a default value of 0 or false. The sole exception to this rule is the char type which does not have an implicit default value.

A property with a default value is not implicitly optional. If a non-optional configuration item with a default value is explicitly specified to have an empty value, the application will report a configuration error and will not start. If it is desired for a property to have a default value and also be optional, it must have an Optional type as described above.

Configuration values are always collected into grouping classes which are marked with the @io.quarkus.runtime.annotations.ConfigGroup annotation. These classes contain a field for each key within its group. In addition, configuration groups can be nested.

A Map can be used for configuration at any position where a configuration group would be allowed. The key type of such a map must be String, and its value may be either a configuration group class or a valid leaf type. The configuration key segment following the map’s key segment will be used as the key for map values.

Configuration roots are configuration groups that appear in the root of the configuration tree. A configuration property’s full name is determined by joining the string quarkus. with the hyphenated name of the fields that form the path from the root to the leaf field. For example, if I define a configuration root group called ThreadPool, with a nested group in a field named sizing that in turn contains a field called minSize, the final configuration property will be called quarkus.thread-pool.sizing.min-size.

A configuration root’s name can be given with the name property, or it can be inferred from the class name. If the latter, then the configuration key will be the class name, minus any Config or Configuration suffix, broken up by camel-case, lowercased, and re-joined using hyphens (-).

A configuration root’s class name can contain an extra suffix segment for the case where there are configuration roots for multiple Configuration Root Phases. Classes which correspond to the BUILD_TIME and BUILD_AND_RUN_TIME_FIXED may end with BuildTimeConfig or BuildTimeConfiguration, and classes which correspond to the RUN_TIME phase may end with RuntimeConfig, RunTimeConfig, RuntimeConfiguration or RunTimeConfiguration.

Note: The current implementation is still using injection site to determine the root set, so to avoid migration problems, it is recommended that the injection site (field or parameter) have the same name as the configuration root class until this change is complete.

A configuration property name can be split into segments. For example, a property name like quarkus.log.file.enable can be split into the following segments:

A corresponding application.properties for the above example could be:

Since format is not defined in these properties, the default value from @ConfigItem will be used instead.

You can use enhanced conversion of a config item by using the @ConvertWith annotation which accepts a Converter class object. If the annotation is present on a config item, the implicit or custom built in converter in use will be overridden by the value provided. To do, see the example below which converts YES or NO values to boolean.

The corresponding application.properties will look like.

io.quarkus.deployment.recording.RecorderContext provides some convenience methods to enhance bytecode recording, this includes the ability to register creation functions for classes without no-arg constructors, to register an object substitution (basically a transformer from a non-serializable object to a serializable one and vice versa), and to create a class proxy. This interface can be directly injected as a method parameter into any @Record method.

Calling classProxy with a given class name will create a Class that can be passed into recorder methods, and at runtime will be substituted with the class whose name was passed in to classProxy. This is basically a convenience to avoid the need to explicitly load classes in the recorders.

As a CDI based runtime, Quarkus extensions often make CDI beans available as part of the extension behavior. However, Quarkus DI solution does not support CDI Portable Extensions. Instead, Quarkus extensions can make use of various Build Time Extension Points.

If the library exposes metrics by itself, we don’t have to do much. However, there are a few points to consider:

In this case, the extension can make use of the quarkus-smallrye-metrics-spi module to expose the metrics from the library using MP Metrics.

You should do the following:

An example build step for build-time registration of metrics:

In this example, there is a gauge per each data source that shows the current number of active connections. In this example, we provide an object that implements the logic of the metric, in the case of a gauge, it needs to implement org.eclipse.microprofile.metrics.Gauge. Example:

When registering gauges, it is required to provide a custom object that implements the correct metric type. For metric types other than gauges, this is optional - you can choose whether to provide an implementation, or whether the default implementation class from SmallRye Metrics should be instantiated for the metric and registered in the metric registry. To update the metric value, it will be necessary to look them up in the metric registry and call the methods specific to each metric type.

Look into the AgroalProcessor#registerMetrics method for an example how this was done for the Agroal extension.

In this case, the dependency setup and build-time registration is the same as in case 2. The difference will be that instead of introducing custom metric objects that bridge between library-specific metrics and MP Metrics, the extension’s code will contain metric collection code like this:

In this case, be aware that the MP Metrics API and implementation might not be available on the runtime classpath! This is why there is a if(metricsEnabled) check that should make sure that if metrics are not enabled, we don’t touch MP Metrics classes, because that would fail. The extension itself will need to provide such check, and it must return true only if both of these conditions hold:

The recommended way to implement this check would be to produce a specific SystemPropertyBuildItem during build, which will make it easy to evaluate these two conditions, and then check back to this system property at runtime. Example:

First, add an optional dependency to quarkus-jsonb on your extension’s runtime module.

Then create a serializer and/or a deserializer for JSON-B, an example of which can be seen in the mongodb-panache extension.

Add a dependency to quarkus-jsonb-spi on your extension’s deployment module.

Add a build step to your processor to register the serializer via the JsonbSerializerBuildItem.

The JSON-B extension will then use the produced build item to register your serializer/deserializer automatically.

If you need more customization capabilities than registering a serializer or a deserializer, you can produce a CDI bean that implements io.quarkus.jsonb.JsonbConfigCustomizer via an AdditionalBeanBuildItem. More info about customizing JSON-B can be found on the JSON guide Configuring JSON support

First, add an optional dependency to quarkus-jackson on your extension’s runtime module.

Then create a serializer or a deserializer (or both) for Jackson, an example of which can be seen in the mongodb-panache extension.

Add a dependency to quarkus-jackson-spi on your extension’s deployment module.

Add a build step to your processor to register a Jackson module via the JacksonModuleBuildItem. You need to name your module in a unique way across all Jackson modules.

The Jackson extension will then use the produced build item to register a module within Jackson automatically.

If you need more customization capabilities than registering a module, you can produce a CDI bean that implements io.quarkus.jackson.ObjectMapperCustomizer via an AdditionalBeanBuildItem. More info about customizing Jackson can be found on the JSON guide Configuring JSON support

The only particular aspect of writing Quarkus extensions in Eclipse is that APT (Annotation Processing Tool) is required as part of extension builds, which means you need to:

The class augmentation step of Quarkus generates classes for various purposes. Sometimes you need to view these classes/bytecode to debug or understand an issue. Classes that are related to application augmentation are currently held in memory in a runtime class loader.

When using the dev mode (running ./mvnw clean compile quarkus:dev) you can have these classes written out to disk for inspection, for this, you need to specify the quarkus.debug.generated-classes-dir system property, for example:

You will see a line of log for each class outputed to the directory:

It’s not uncommon to develop an extension in a multi-module Maven project that also contains an "example" module. However, if you want to run the example in the development mode then the -DnoDeps system property must be used in order to exclude the local project dependencies. Otherwise, Quarkus attempts to monitor the extension classes and this may result in weird class loading issues.

When you start a Quarkus instance, you will see a line like the one highlighted in this example:

The features listed reflect the types of extensions that are installed. An extension declares its display name using a Build Step Processors method that produces a FeatureBuildItem like this TestProcessor#featureBuildItem() method example:

The feature name should map to a label in the extension’s devtools/common/src/main/filtered/extensions.json entry so that the feature name displayed by the startup line matches a label that one can used to select the extension when creating a project using the Quarkus maven plugin as shown in this example taken from the Writing JSON REST Services guide where the "resteasy-jsonb" feature is referenced:

The CDI layer processes CDI beans that are either explicitly registered or that it discovers based on bean defining annotations as defined in 2.5.1. Bean defining annotations. You can expand this set of annotations to include annotations your extension processes using a BeanDefiningAnnotationBuildItem as shown in this TestProcessor#registerBeanDefinningAnnotations example:

One of the main things an extension is likely to do is completely separate the configuration phase of behavior from the runtime phase. Frameworks often do parsing/load of configuration on startup that can be done during build time to both reduce the runtime dependencies on frameworks like xml parsers as well as reducing the startup time the parsing incurs.

An example of parsing a XML config file using JAXB is shown in the TestProcessor#parseServiceXmlConfig method: .Parsing an XML Configuration into Runtime XmlConfig Instance

Typically one is loading a configuration to create some runtime component/service as parseServiceXmlConfig is doing. We will come back to the rest of the behavior in parseServiceXmlConfig in the following Manage Non-CDI Service section.

If for some reason you need to parse the config and use it in other build steps in an extension processor, you would need to create an XmlConfigBuildItem to pass the parsed XmlConfig instance around.

If your extension defines annotations or interfaces that mark beans needing to be processed, you can locate these beans using the Jandex API, a Java annotation indexer and offline reflection library. The following TestProcessor#scanForBeans method shows how to find the beans annotated with our @TestAnnotation that also implement the IConfigConsumer interface:

You can use the io.quarkus.arc.runtime.BeanContainer interface to interact with your extension beans. The following configureBeans methods illustrate interacting with the beans scanned for in the previous section:

A common purpose for an extension is to integrate a non-CDI aware service into the CDI based Quarkus runtime. Step 1 of this task is to load any configuration needed in a STATIC_INIT build step as we did in Parsing Config to Objects. Now we need to create an instance of the service using the configuration. Let’s return to the TestProcessor#parseServiceXmlConfig method to see how this can be done.

The Quarkus container supports startup and shutdown lifecycle events to notify components of the container startup and shutdown. There are CDI events fired that components can observe are illustrated in this example:

What is the relevance of startup and shutdown events for extension authors? We have already seen the use of a ShutdownContext to register a callback to perform shutdown tasks in the Starting a Service section. These shutdown tasks would be called after a ShutdownEvent had been sent.

A StartupEvent is fired after all io.quarkus.deployment.builditem.ServiceStartBuildItem producers have been consumed. The implication of this is that if an extension has services that application components would expect to have been started when they observe a StartupEvent, the build steps that invoke the runtime code to start those services needs to produce a ServiceStartBuildItem to ensure that the runtime code is run before the StartupEvent is sent. Recall that we saw the production of a ServiceStartBuildItem in the previous section, and it is repeated here for clarity:

Not all configuration or resources can be consumed at build time. If you have classpath resources that the runtime needs to access, you need to inform the build phase that these resources need to be copied into the native image. This is done by producing one or more NativeImageResourceBuildItem or NativeImageResourceBundleBuildItem in the case of resource bundles. Examples of this are shown in this sample registerNativeImageResources build step:

If you are using META-INF/services files you need to register the files as resources so that your native image can find them, but you also need to register each listed class for reflection so they can be instantiated or inspected at run-time:

While this is the easiest way to get your services running natively, it’s less efficient than scanning the implementation classes at build time and generating code that registers them at static-init time instead of relying on reflection.

You can achieve that by adapting the previous build step to use a static-init recorder instead of registering classes for reflection:

Objects created during the build phase that are passed into the runtime need to have a default constructor in order for them to be created and configured at startup of the runtime from the build time state. If an object does not have a default constructor you will see an error similar to the following during generation of the augmented artifacts:

There is a io.quarkus.runtime.ObjectSubstitution interface that can be implemented to tell Quarkus how to handle such classes. An example implementation for the DSAPublicKey is shown here:

An extension registers this substitution by producing an ObjectSubstitutionBuildItem as shown in this TestProcessor#loadDSAPublicKey fragment:

The Graal SDK supports substitutions of classes in the native image. An example of how one could replace the XmlConfig/XmlData classes with versions that have no JAXB annotation dependencies is shown in these example classes: