Writing your own extension - Quarkus

Quarkus extensions add a new developer focused behavior to the core offering, and consist of two distinct parts, buildtime augmentation and runtime container. The augmentation part is responsible for all metadata processing, such as reading annotations, XML descriptors etc. The output of this augmentation phase is recorded bytecode which is responsible for directly instantiating the relevant runtime services.
This means that metadata is only processed once at build time, which both saves on startup time, and also on memory usage as the classes etc that are used for processing are not loaded (or even present) in the runtime JVM.
This section is a work in progress and gathers the philosophy under which extensions should be designed and written.
Quarkus’s mission is to transform your entire application including the libraries it uses, into an artifact that uses significantly less resources than traditional approaches. These can then be used to build native applications using GraalVM. To do this you need to analyze and understand the full "closed world" of the application. Without the full and complete context, the best that can be achieved is partial and limited generic support. By using the Quarkus extension approach, we can bring Java applications in line with memory footprint constrained environments like Kubernetes or cloud platforms.
The Quarkus extension framework results in significantly improved resource utilization even when GraalVM is not used (e.g. in HotSpot). Let’s list the actions an extension performs:
Gather build time metadata and generate code
This part has nothing to do with GraalVM, it is how Quarkus starts frameworks “at build time”
The extension framework facilitates reading metadata, scanning classes as well as generating classes as needed
A small part of the extension work is executed at runtime via the generated classes, while the bulk of the work is done at build time (called deployment time)
Enforce opinionated and sensible defaults based on the close world view of the application (e.g. an application with no @Entity does not need to start Hibernate ORM)
An extension hosts Substrate VM code substitution so that libraries can run on GraalVM
Most changes are pushed upstream to help the underlying library run on GraalVM
Not all changes can be pushed upstream, extensions host Substrate VM substitutions - which is a form of code patching - so that libraries can run
Host Substrate VM code substitution to help dead code elimination based on the application needs
This is application dependent and cannot really be shared in the library itself
For example, Quarkus optimizes the Hibernate code because it knows it only needs a specific connection pool and cache provider
Send metadata to GraalVM for example classes in need of reflection
This information is not static per library (e.g. Hibernate) but the framework has the semantic knowledge and knows which classes need to have reflection (for example @Entity classes)
As much as possible favor doing work at build time (deployment part of the extension) as opposed to let the framework do work at startup time (runtime). The more is done there, the smaller Quarkus applications using that extension will be and the faster they will load.
Quarkus simplifies the most common usages. This means that its defaults might be different from the library it integrates.
To make the simple experience easiest, unify the configuration in application.properties via SmallRye Config. Avoid library specific configuration files, or at least make them optional: e.g. persistence.xml for Hibernate ORM is optional.
Extensions should see the configuration holistically as a Quarkus application instead of focusing on the library experience. For example quarkus.database.url and friends are shared between extensions as defining a database access is a shared task (instead of a hibernate. property for example). The most useful configuration options should be exposed as quarkus.[extension]. instead of the natural namespace of the library. Less common properties can live in the library namespace.
To fully enable the close world assumptions that Quarkus can optimize best, it is better to consider configuration options as build time settled vs overridable at runtime. Of course properties like host, port, password should be overridable at runtime. But many properties like enable caching or setting the JDBC driver can safely require a rebuild of the application.
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.
Since CDI is the central programming model when it comes to component composition, frameworks and extensions should expose their components as beans that are easily consumable by user applications. For example, Hibernate ORM exposes EntityManagerFactory and EntityManager beans, the connection pool exposes DataSource beans etc. Extensions must register these bean definitions at build 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