Writing Your Own Extension

If the extension provides additional Config Sources and if these are required during Static Init, these must be registered with StaticInitConfigBuilderBuildItem. Configuration in Static Init does not scan for additional sources to avoid double initialization at application startup time.

An extension can produce an AdditionalBeanBuildItem to instruct the container to read a bean definition from a class as if it was part of the original application:

All other beans can inject such a bean:

And vice versa - the extension bean can inject application beans and beans provided by other extensions:

Some components may require additional initialization based on information collected during augmentation. The most straightforward solution is to obtain a bean instance and call a method directly from a build step. However, it is illegal to obtain a bean instance during the augmentation phase. The reason is that the CDI container is not started yet. It’s started during the Static init bootstrap phase.

It is possible to invoke a bean method from a recorder method though. If you need to access a bean in a @Record(STATIC_INIT) build step then is must either depend on the BeanContainerBuildItem or wrap the logic in a BeanContainerListenerBuildItem. The reason is simple - we need to make sure the CDI container is fully initialized and started. However, it is safe to expect that the CDI container is fully initialized and running in a @Record(RUNTIME_INIT) build step. You can obtain a reference to the container via CDI.current() or Quarkus-specific Arc.container().

A very useful pattern of creating such beans but also giving application code the ability to easily override some beans with custom implementations, is to use the @DefaultBean that Quarkus provides. This is best explained with an example.

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:

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.

There are several ways to register a synthetic bean in Quarkus. In this chapter, we will cover a use case that can be used to initialize extension beans in a safe manner (compared to Bean initialization).

The SyntheticBeanBuildItem can be used to register a synthetic bean:

You will need to include the io.quarkus:quarkus-extension-maven-plugin and configure the maven-compiler-plugin to detect the quarkus-extension-processor annotation processor to collect and generate the necessary Quarkus extension metadata for the extension artifacts, if you are using the Quarkus parent pom it will automatically inherit the correct configuration.

You will also need to configure the maven-compiler-plugin of the deployment module to detect the quarkus-extension-processor annotation processor.

You will need to apply the io.quarkus.extension plugin in the runtime module of your extension project. The plugin includes the extensionDescriptor task that will generate META-INF/quarkus-extension.properties and META-INF/quarkus-extension.yml files. The plugin also enables the io.quarkus:quarkus-extension-processor annotation processor in both deployment and runtime modules to collect and generate the rest of the Quarkus extension metadata. The name of the deployment module can be configured in the plugin by setting the deploymentModule property. The property is set to deployment by default:

A build step is a non-static 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 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 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 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.

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.

The index of scanned classes will not automatically include your external class dependencies. To add dependencies, create a @BuildStep that produces IndexDependencyBuildItem objects, for a groupId and artifactId.

The Amazon Alexa extension adds dependent libraries from the Alexa SDK that are used in Jackson JSON transformations, in order for the reflective classes to identified and included at BUILD_TIME.

With the artifacts added to the Jandex indexer, you can now search the index to identify classes implementing an interface, subclasses of a specific class, or classes with a target annotation.

For example, the Jackson extension uses code like below to search for annotations used in JSON deserialization, and add them to the reflective hierarchy for BUILD_TIME analysis.

It can occasionally be useful to see a visual representation of the interactions between the various build steps. For such cases, adding -Dquarkus.builder.graph-output=build.dot when building an application will result in the creation of the build.dot file in the project’s root directory. See this for a list of software that can open the file and show the actual visual representation.

Configuration mappings are strictly bound by configuration phase, and attempting to access a configuration mapping from outside its corresponding phase will result in an error. They dictate when its contained keys are read from the configuration, and when they are available to applications. The phases defined by io.quarkus.runtime.annotations.ConfigPhase are as follows:

For all cases other than the BUILD_TIME case, the configuration mapping interface and all the configuration groups and types contained therein must be located in, or reachable from, the extension’s run time artifact. Configuration mappings of phase BUILD_TIME may be located in or reachable from either of the extension’s run time or deployment artifacts.

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 @WithDefault will be used instead.

A configuration mapping name can contain an extra suffix segment for the case where there are configuration mappings for multiple Config Phases. Classes which correspond to the BUILD_TIME and BUILD_AND_RUN_TIME_FIXED may end with BuildTimeConfig or BuildTimeConfiguration, classes which correspond to the RUN_TIME phase may end with RuntimeConfig, RunTimeConfig, RuntimeConfiguration or RunTimeConfiguration.

The configuration is an important part of each extension and therefore needs to be properly documented. Each configuration property should have a proper Javadoc comment.

While it is handy to have the documentation available when coding, the configuration documentation must also be available in the extension guides. The Quarkus build automatically generates the configuration documentation based on the Javadoc comments, but it needs to be explicitly included in each guide.

One of the main outputs of the build process is recorded bytecode. This bytecode actually sets up the runtime environment. For example, in order to start Undertow, the resulting application will have some bytecode that directly registers all Servlet instances and then starts Undertow.

As writing bytecode directly is complex, this is instead done via bytecode recorders. At deployment time, invocations are made on recorder objects that contain the actual runtime logic, but instead of these invocations proceeding as normal they are intercepted and recorded (hence the name). This recording is then used to generate bytecode that performs the same sequence of invocations at runtime. This is essentially a form of deferred execution where invocations made at deployment time get deferred until runtime.

Let’s look at the classic 'Hello World' type example. To do this the Quarkus way we would create a recorder as follows:

And then create a build step that uses this recorder:

When this build step is run nothing is printed to the console. This is because the HelloRecorder that is injected is actually a proxy that records all invocations. Instead, if we run the resulting Quarkus program we will see 'Hello World' printed to the console.

Methods on a recorder can return a value, which must be proxiable (if you want to return a non-proxiable item wrap it in io.quarkus.runtime.RuntimeValue). These proxies may not be invoked directly, however they can be passed into other recorder methods. This can be any recorder method, including from other @BuildStep methods, so a common pattern is to produce BuildItem instances that wrap the results of these recorder invocations.

For instance, in order to make arbitrary changes to a Servlet deployment Undertow has a ServletExtensionBuildItem, which is a MultiBuildItem that wraps a ServletExtension instance. I can return a ServletExtension from a recorder in another module, and Undertow will consume it and pass it into the recorder method that starts Undertow.

At runtime the bytecode will be invoked in the order it is generated. This means that build step dependencies implicitly control the order that generated bytecode is run. In the example above we know that the bytecode that produces a ServletExtensionBuildItem will be run before the bytecode that consumes it.

The following objects can be passed to recorders:

Configuration objects with phase RUNTIME or BUILD_AND_RUNTIME_FIXED can be injected into recorders via constructor injection. Just create a constructor that takes the configuration objects the recorder needs. If the recorder has multiple constructors you can annotate the one you want Quarkus to use with @Inject. If the recorder wants to inject runtime config but is also used at static init time then it needs to inject a RuntimeValue<ConfigObject>, this value will only be set when the runtime methods are being invoked.

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 fully-qualified class name will create a Class instance that can be passed into a recorder method, and at runtime will be substituted with the class whose name was passed in to classProxy(). However, this method should not be needed in most use cases because directly loading deployment/application classes at processing time in build steps is safe. Therefore, this method is deprecated. Nonetheless, there are some use cases where this method comes in handy, such as referring to classes that were generated in previous build steps using GeneratedClassBuildItem.

In some scenarios, more significant manipulation of bytecode may be needed. If bytecode recording isn’t sufficient, Gizmo is a convenient alternative to ASM, with a higher-level API.

Extensions often need a way to determine whether a given class is part of the application’s runtime classpath. The proper way for an extension to perform this check is to use io.quarkus.bootstrap.classloading.QuarkusClassLoader.isClassPresentAtRuntime.

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 directly uses a metrics API, there are two options:

Extensions may need to provide a fallback if there is no active metrics extension or the extension doesn’t support the API required by the library.

There are two examples of a library providing its own metrics API:

To define your own metrics from scratch, you have two basic options: Use the generic MetricFactory builders, or follow the binder pattern, and create instrumentation specific to the enabled metrics extension.

To use the extension-agnostic MetricFactory API, your processor can define a BuildStep that produces a MetricsFactoryConsumerBuildItem that uses a RUNTIME_INIT or STATIC_INIT Recorder to define a MetricsFactory consumer.

+

+ - The associated recorder should use the provided MetricsFactory to register metrics, for example

+

Remember that metrics extensions are optional. Keep metrics-related initialization isolated from other setup for your extension, and structure your code to avoid eager imports of metrics APIs. Gathering metrics can also be expensive. Consider using additional extension-specific configuration to control behavior of metrics if the presence/absence of metrics support isn’t sufficient.

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

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

When Quarkus is starting the io.quarkus.deployment.builditem.LiveReloadBuildItem is guaranteed to be present that gives information about this start, in particular:

It also provides a global context map you can use to store information between restarts, without needing to resort to static fields.

Live reload is generally triggered by an HTTP request, however not all applications are HTTP applications and some extensions may want to trigger live reload based on other events. To do this you need to implement io.quarkus.dev.spi.HotReplacementSetup in your runtime module, and add a META-INF/services/io.quarkus.dev.spi.HotReplacementSetup that lists your implementation.

On startup the setupHotDeployment method will be called, and you can use the provided io.quarkus.dev.spi.HotReplacementContext to initiate a scan for changed files.

Where extensions use an external service, adding a Dev Service can improve the user experience in development and test modes. See how to write a Dev Service for more details.

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:

Quarkus generates a lot of classes during the build phase and in many cases also transforms existing classes. It is often extremely useful to see the generated bytecode and transformed classes during the development of an extension.

If you set the quarkus.package.jar.decompiler.enabled property to true then Quarkus will download and invoke the Vineflower decompiler and dump the result in the decompiled directory of the build tool output (target/decompiled for Maven for example). The output directory can be changed with quarkus.package.jar.decompiler.output-dir.

There are also three system properties that allow you to dump the generated/transformed classes to the filesystem and inspect them later, for example via a decompiler in your IDE.

These properties are especially useful in the development mode or when running the tests where the generated/transformed classes are only held in memory in a class loader.

For example, you can specify the quarkus.debug.generated-classes-dir system property to have these classes written out to disk for inspection in the development mode:

You should see a line in the log for each class written to the directory:

The property is also honored when running tests:

Analogously, you can use the quarkus.debug.transformed-classes-dir and quarkus.debug.generated-sources-dir properties to dump the relevant output.

When using QuarkusUnitTest, as an alternative to setting quarkus.debug.*-dir manually, you may simply call QuarkusUnitTest#debugBytecode:

This will automatically set up these configuration properties so that classes/sources are dumped to target/debug, for that test class only, in a subdirectory that is unique to each test execution. See the javadoc of QuarkusUnitTest#debugBytecode for details.

This is handy to debug flaky tests that happen only in the CI environment, in particular; for example the GitHub Actions CI at https://github.com/quarkusio/quarkus/ is set up so that such target/debug directories are collected into build artifacts available for download after each CI run.

When using QuarkusUnitTest, if you need to enable trace logs for a particular test class, you may simply call QuarkusUnitTest#traceCategories and pass the logging categories in argument:

See the javadoc of QuarkusUnitTest#traceCategories for details.

This is handy to debug flaky tests that happen only in the CI environment, in particular, as this will only increase the verbosity of logs in the particular test where the option is enabled.

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.

Remember to add IndexDependencyBuildItem artifacts to your @BuildStep.

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 an XML config file using JAXB is shown in the TestProcessor#parseServiceXmlConfig method:

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: