Build items

The io.smallrye.config.ConfigMapping classes that must be registered with io.smallrye.config.SmallRyeConfig.

While ConfigMappingBuildItem represents each discovered io.smallrye.config.ConfigMapping class, this build item collects only the config mappings with active injection points (or marked as unremovable), expanding all prefix overrides for the same config class, since io.smallrye.config.SmallRyeConfig requires a separate registration for each class and prefix combination.

The map key is the fully qualified config class name, and the value is the set of prefixes under which it must be registered.

See ConfigMappingBuildItem

The org.eclipse.microprofile.config.inject.ConfigProperties that must be registered with io.smallrye.config.SmallRyeConfig.

While ConfigPropertiesBuildItem represents each discovered org.eclipse.microprofile.config.inject.ConfigProperties class, this build item collects only the config properties with active injection points (or marked as unremovable), expanding all prefix overrides for the same config class, since io.smallrye.config.SmallRyeConfig requires a separate registration for each class and prefix combination.

The map key is the fully qualified config class name, and the value is the set of prefixes under which it must be registered.

See ConfigPropertiesBuildItem

A MultiBuildItem used to register console commands.

Extensions can produce this build item to contribute AEsh commands that are made available in the Quarkus interactive console.

Build item that signifies that the interactive console is ready.

This will not always be present, as the console may not be installed

Holds a context handler used to propagate context when executing tasks.

Build Item that can be used to queue shutdown tasks that are run when the io.quarkus.bootstrap.app.CuratedApplication is closed.

For production applications, this will be at the end of the Maven/Gradle build. For dev mode applications, this will be when dev mode shuts down. For tests, it will generally be at the end of the test run. However, for continuous testing this will be when the outer dev mode process shuts down. For extension unit tests, this will usually be the end of the test.

A SimpleBuildItem that represents the aggregate result of all deployment actions. This is used by build tools to report back the overall outcome of the deployment process.

It contains a list of DeployCommandActionBuildItem instances, each representing an individual deployment action and its result.

See DeployCommandActionBuildItem @since 3.8.0

No Javadoc found

A build item describing a Dev Service that has been started by Quarkus.

Each instance provides details about a specific Dev Service, including:

This information is often used for display, for example, in the Dev UI or console logs, to inform the developer about the running Dev Services and their configurations.

BuildItem for running services provided by compose

Build item that contains the final results of all configuration.

This is a wrapper around the RunningDevServicesRegistry, so the registry can be loaded with the system classloader The QuarkusClassLoader takes care of loading the tracker with the right classloader

This build item is used to manage the lifecycle of dev services across different features and launch modes.

A marker build item that indicates, if any instances are provided during the build, the containers started by DevServices may use a shared network. This is mainly useful in integration tests where the application container needs to be able to communicate with the service containers.

Allows disabling of instrumentation based reload if the index of changed classes matches certain criteria

Contains the IDE to be opened when a request to open a class is made

A build item that allows extension to configure the native-image compiler to effectively ignore certain configuration files in specific jars.

The jarFile property specifies the name of the jar file or a regular expression that can be used to match multiple jar files. Matching jar files using regular expressions should be done as a last resort.

The resourceName property specifies the name of the resource file or a regular expression that can be used to match multiple resource files. For the match to work, the resources need to be part of the matched jar file(s) (see jarFile). Matching resource files using regular expressions should be done as a last resort.

See https://github.com/oracle/graal/pull/3179 for more details.

Carries a predicate that identifies methods that can have annotations which affect the execution model (@Blocking, @NonBlocking, @RunOnVirtualThread).

Used to detect wrong usage of these annotations, as they are implemented directly by the various frameworks and may only be put on "entrypoint" methods. Placing these annotations on methods that can only be invoked by application code is always wrong.

A build item indicating that a specific Quarkus extension requires SSL support in native mode.

This is a MultiBuildItem. Each instance signifies that the extension named in the #extension field needs the necessary native SSL configuration (like certificates) included in the native image build. It can be instantiated using either a Feature enum constant or directly with the extension’s name string.

Used to register an upcall/downcall signature for FFI/FFM runtime access.

Used to register an upcall signature for FFI/FFM runtime access.

A build item representing a Java class file generated during the build process.

This is a MultiBuildItem. Each instance holds information about a single generated class:

These generated classes are typically added to the application’s class path or packaged into the final artifact.

Used when resources generated by the build should not end up in the produced runnable artifact, but in the file system inside the output directory of OutputTargetBuildItem.

This is written to the file system for normal and dev mode, but not for test mode.

A generated class that is only applicable to native images.

Represents a system property that will be set immediately on application startup, the system property will be generated when set.

Identifies a file from a io.quarkus.bootstrap.devmode.DependenciesFilter#getReloadableModules(io.quarkus.bootstrap.model.ApplicationModel) reloadable module that, if modified, may result in a hot redeployment when in the dev mode.

A file may be identified with an location or a matching predicate. See Builder#setLocation(String) and Builder#setLocationPredicate(Predicate).

The location may be:

If multiple build items match the same file then the final value of restartNeeded is computed as a logical OR of all the #isRestartNeeded() values.

Build item that defines dependencies that should be indexed. This can be used when a dependency does not contain a marker file (e.g. META-INF/beans.xml).

A symbolic class that represents that an initialization task has been completed. Similar to ServiceStartBuildItem but focused on initialization tasks (e.g. db migrations etc) that are run during runtime just before the application starts.

The build item is used, so that we can track when all initialization tasks have been completed.

A build item that indicates that a Java package should be exported using '-J—​add-exports' option to become visible to native-image

Build item that holds the results of dependency usage analysis for tree shaking. Contains whether class-level tree shaking was performed, the set of reachable class names (dot-separated), and the sorted list of removed class resource paths per dependency.

This build item is meant to be internal to io.quarkus.deployment.pkg.steps.JarTreeShakeProcessor, in a sense it’s produced and consumed by it.

Declares a class that must be treated as a root for jar tree-shake reachability analysis. Any class registered through this build item will not be removed by the tree-shaker, and all classes reachable from it will also be preserved.

Used to register a class for JNI runtime access.

JNI access registration fine-grained to single methods for a given class.

Build item to indicate to the various steps that generation of a JVM startup archive has been requested

Used to register a lambda capturing type in native mode

A build item that can be used to query the live reload state.

It can also be used to store context information that is persistent between hot reloads.

A build item containing the default minimum log levels for specific log categories. Minimum log levels (io.quarkus.runtime.logging.InheritableLevel).

The log console format build item. Producing this item will cause the logging subsystem to disregard its console logging formatting configuration and use the formatter provided instead. If multiple formatters are enabled at run time, a warning message is printed and only one is used.

A build item for adding additional logging handlers.

The socket format build item. Producing this item will cause the logging subsystem to disregard its socket logging formatting configuration and use the formatter provided instead. If multiple formatters are enabled at runtime, a warning message is printed and only one is used.

The syslog format build item. Producing this item will cause the logging subsystem to disregard its syslog logging formatting configuration and use the formatter provided instead. If multiple formatters are enabled at runtime, a warning message is printed and only one is used.

No Javadoc found

Holds the name of the main class for the application.

A metrics provider will iterate over all MetricsFactory consumers, allowing them to register metrics via bytecode recording

This will generate the equivalent of "--add-opens=[openedModule/package(s)]=[openingModule]" for all runners of the generated application. Some limitations apply which will depend on the launch mode of Quarkus; specifically, when generating a runnable Jar we can only open a module to ALL-UNNAMED; this is considered acceptable at the time of writing as extensions are generally placed on the classpath for both fast-jar and uber-jar packaging formats. We expect this to evolve as further packaging formats are introduced which would better leverage the module system. We specifically don’t allow opening a module to "ALL-UNNAMED" explicitly to encourage using the module names that a library has or will have in the near future: for this reason, when a module name is provided which doesn’t exist, we map it to the unnamed module. This should be treated as an implementation detail of the current packaging format and is most likely bound to evolve. When running integration tests, we aim to run the tests within module access rules consistent with the production packaging modes, but as we need to dynamically modify the module system’s access restrictions we need to apply these rules to specific, targeted classloaders: we’ll only instrument the unnamed module relating to the Quarkus app classloader. This should be effective but is based on the general understanding that libraries within Quarkus shouldn’t use custom classloaders; should this assumption be violated, there’s the risk of a "module opens" instruction to not be applied automatically, and users would be required to issue the matching command line flags.

Native configuration generated by native image agent can be integrated directly into subsequence native build steps, if the user enables NativeConfig#agentConfigurationApply(). This build item is used to transfer the native configuration folder path onto the io.quarkus.deployment.pkg.steps.NativeImageBuildStep. If the build item is passed, the directory is added to the native image build execution.

A build item representing the successfully built native image.

This item is produced after the native image build process completes. It contains:

The GraalVMVersion inner class provides details about the GraalVM distribution, version, and Java version.

Indicates that all charsets should be enabled in native image.

A build item that represents a java.lang.reflect.Proxy definition that will be required in native mode. This definition takes the form of an ordered list of interfaces that this proxy will implement.

Indicates that a resource bundle should be included in the native image

A build item that indicates that a set of resource paths defined by regular expression patterns or globs should be included in the native image.

Globs passed to the includeGlob*() methods of the Builder are transformed to regular expressions internally. See NativeConfig.ResourcesConfig#includes for the supported glob syntax.

The patterns are passed to the native image builder using resource-config.json. The same mechanism (and regular expression syntax) is used by native-image’s `-H:ResourceConfigurationFiles, -H:IncludeResources and -H:ExcludeResources (since GraalVM 20.3.0) command line options.

Related build items:

A build item that indicates that a security provider should be included in the native image using '-H:AdditionalSecurityProviders' option

A system property that will be set at native image build time

A build item that indicates whether native monitoring is enabled and which option from NativeConfig.MonitoringOption. To be used in the native image generation.

Indicates that the OpenTelemetry SDK is present and carries the build-time enabled state for each telemetry signal (tracing, metrics, logging) and a check if the OTel SDK is enabled at runtime. This can be used to decide if OTel instrumentation needs to be instantiated, or activated.

Produced by the OpenTelemetry extension’s deployment module. Other extensions should consume it as an Optional so they still work when the OpenTelemetry extension is not on the classpath.

The build-time flags reflect the following configuration properties:

Each signal is only active when both its own flag <em>and</em> the top-level quarkus.otel.enabled flag are true.

The convenience method #isOtelSdkEnabled(Optional) extracts the runtime-enabled RuntimeValue when the build item is present:

A build item that represents the status of the Podman container runtime.

This class extends ContainerRuntimeStatusBuildItem and provides a specific implementation for checking the availability of the Podman runtime.

A build item that can be used to register pre-init tasks that will be executed early in GeneratedMain.

For now, these tasks are only executed when using the AOT runner.

Pre-init is run at the very beginning of the GeneratedMain, and all tasks are submitted to a thread pool that will execute the tasks in parallel so don’t expect any execution ordering.

The tasks are submitted to the thread pool in the priority order: a lower value for priority will be submitted first.

Extension build steps can produce this if preloading classes is enabled.

Holds the name of the class implementing io.quarkus.runtime.QuarkusApplication.

This allows other build steps to identify the main application class It stores the fully qualified class name as a String.

A build item that represents the raw command line arguments as they were passed to the application.

This can be passed directly to bytecode recorders that take a Supplier<String[]>.

No filtering is done on these parameters.

Indicates that the given class should be instantiated with the constructor with the most parameters when the object is bytecode recorded.

An alternative to RecordableConstructorBuildItem for when the objects cannot be annotated

Used to define a condition to register a class for reflection in native mode only when a specific type is reachable.

See ReflectiveClassBuildItem See ReflectiveFieldBuildItem See ReflectiveMethodBuildItem See ReflectiveHierarchyBuildItem

Attempts to register a complete type hierarchy for reflection.

This is intended to be used to register types that are going to be serialized, e.g. by Jackson or some other JSON mapper.

This will do 'smart discovery' and in addition to registering the type itself it will also attempt to register the following:

This discovery is applied recursively, so any additional types that are registered will also have their dependencies discovered.

Registering methods for reflective access during the build

Marker build item for augmentation runs that only compare generated bytecode for reproducibility.

Represents the result of executing multiple command actions during the build process. It contains a list of RunCommandActionBuildItem for completed commands.

A build item which specifies a configuration default value for run time.

A class that will be initialized at runtime in native mode.

Aggregates SBOMs generated for packaged applications. The API around this is still in development and will likely change in the near future.

Resource to be included in the application archive as part of SBOM generation.

SBOM generators must use this build item instead of io.quarkus.deployment.builditem.GeneratedResourceBuildItem to avoid build-step cycles with tree-shake analysis, which collects roots from GeneratedResourceBuildItem instances.

A symbolic class that represents a service start.

StartupEvent is fired after all services are started.

A build item that holds a ShutdownListener instance.

Allows registration of listeners to be notified during application shutdown.

It should be noted, that in most cases, this build item should not be used and instead extensions should opt for ShutdownContext (via ShutdownContextBuildItem)

Marker item to specify that SnapStart is enabled.

A build item holding a BytecodeRecorderImpl instance used for generating static initializer bytecode.

Indicates that the static init logging setup has been done.

See LoggingSetupBuildItem when you want the full logging subsystem to be properly initialized with runtime configuration.

Allows extensions to suppress the runtime warning that Quarkus emits on startup when a non-runtime configuration option is different at runtime than build time. An example usage of this is when a user provides some test value in application.properties for a build-time only property and only provides the actual value on the command line when starting Quarkus. In such a case we don’t want the value set at build time to be revealed at runtime as it could be sensitive.

This is an optional build item that allows us to track annotations that will define test classes. It is only available during tests.

This is an optional build item that allows extensions to distinguish test classes from application classes. It is only available during tests.

This is an optional build item that represents the current test profile.

It is only available during tests.

holds a ThreadFactory instance, used to configure thread creation for the main executor

Ignore resources when building an Uber Jar

Represents fields that are accessed using unsafe operations. This build item provides information about the class and field names that require special handling during the build process.

A marker build item that is used to indicate that UPX compression was performed

Represents a CLI command class discovered during build-time index scanning.

Produced by the discoverCommands build step and consumed by subsequent steps for mode detection, bean registration, and recorder metadata.

Marker build item indicating that a remote transport (SSH or WebSocket) is available.

Produced by sub-extension deployment processors (e.g. AeshSshProcessor, AeshWebSocketProcessor) to signal that CLI access is available over a remote channel. When present, the core AeshProcessor will skip starting the local console by default.

A build item for JDBC datasources.

If you inject this build item when recording runtime init template calls, you are guaranteed the datasources configuration has been injected and datasources can be created.

Register a JDBC driver for the Agroal extension.

It allows to resolve automatically the driver from the kind, thus users don’t have to set the driver anymore, except if they want to use a specific one.

A build item to represent a JDBC property to be set as an additional JDBC property when the datasource is setup.

No Javadoc found

Allows extensions to override the default mock event server port. Used by amazon-lambda-http and amazon-lambda-rest to avoid port conflicts when the real Vert.x HTTP server also starts in dev mode.

Handler provided by another extension i.e. AWS Lambda HTTP

Make it possible to add, remove or alter annotations on various components. The provided transformer uses AnnotationsTransformer#appliesTo(AnnotationTarget.Kind) to limit the scope of transformer to classes, fields, methods, method params or a combination of those.

These metadata changes are not stored in Jandex directly (Jandex is immutable) but instead in an abstraction layer. Users/extensions can access io.quarkus.arc.processor.AnnotationStore to view the updated annotation model.

This build item can be used to turn a class that is not annotated with a CDI scope annotation into a bean, i.e. the default scope annotation is added automatically if all conditions are met.

Represent a Jandex IndexView on the whole deployment that has a complete CDI-related information. As such, this index should be used for any CDI-oriented work.

Compared to io.quarkus.deployment.builditem.CombinedIndexBuildItem this index can contain additional classes that were indexed while bean discovery was in progress.

See GeneratedBeanBuildItem See io.quarkus.deployment.builditem.CombinedIndexBuildItem

A build item that represents the fully initialized CDI bean container. This item is produced as the last step of the ArC bootstrap process.

This build item is used to specify additional bean defining annotations. See also 2.5.1. Bean defining annotations.

By default, the resulting beans must not be removed even if they are considered unused and ArcConfig#removeUnusedBeans is enabled.

Bean registration phase can be used to register synthetic beans.

An extension that needs to produce other build items during the "bean registration" phase should use this build item. The build step should produce a BeanConfiguratorBuildItem or at least inject a BuildProducer for this build item, otherwise it could be ignored or processed at the wrong time, e.g. after ArcProcessor#validate(BeanRegistrationPhaseBuildItem, List, BuildProducer).

See BeanConfiguratorBuildItem See BeanRegistrar

A type of build item that contains only declaring classes, methods and fields that have been annotated with unsuccessful build time conditions. It aims to be used to manage the exclusion of the annotations thanks to the build time conditions also known as IfBuildProfile, UnlessBuildProfile, IfBuildProperty and UnlessBuildProperty

See io.quarkus.arc.profile.IfBuildProfile See io.quarkus.arc.profile.UnlessBuildProfile See io.quarkus.arc.properties.IfBuildProperty See io.quarkus.arc.properties.UnlessBuildProperty

This build item hold the "final" predicate that is used to distinguish application classes from framework/library classes.

Context registration phase can be used to register custom CDI contexts.

An extension that needs to produce other build items during the "context registration" phase should use this build item. The build step should produce a ContextConfiguratorBuildItem or at least inject a BuildProducer for this build item, otherwise it could be ignored or processed at the wrong time, e.g. after ArcProcessor#registerBeans(ContextRegistrationPhaseBuildItem, List, BuildProducer, BuildProducer, BuildProducer).

Typical workflow involves obtaining a ContextConfigurator via getContext().configure(). Note that there is no need to invoke ContextConfigurator#done() once you are done as it is performed automatically.

See ContextConfiguratorBuildItem See CustomScopeBuildItem

Holds information about all known custom scopes in the deployment and has utility methods allowing to check whether given class has some scope annotation.

This build item is used to specify types to be excluded from discovery.

An element value can be:

If any element value matches a discovered type then the type is excluded from discovery, i.e. no beans and observer methods are created from this type.

Allows extensions to programmatically exclude certain packages from split package detection which is executed by SplitPackageProcessor. Extensions are encouraged to solve split package issues and this build item should be used primarily as temporary workaround.

A package string representation can be:

Represents an intercepted static method.

Makes it possible to register annotations that should be considered interceptor bindings but are not annotated with jakarta.interceptor.InterceptorBinding.

Provides access to InvokerFactory. May only be used in the bean registration phase, observer registration phase, and validation phase (basically, until ArC generates the classes). Afterwards, any attempt to call #createInvoker(BeanInfo, MethodInfo) throws an exception.

An extension that needs to produce other build items during the "synthetic observer registration" phase should use this build item. The build step should produce a ObserverConfiguratorBuildItem or at least inject a BuildProducer for this build item, otherwise it could be ignored or processed at the wrong time, e.g. after ArcProcessor#validate.

See ObserverConfiguratorBuildItem See ObserverRegistrar

A build item that represents the fully initialized CDI bean container. This item is produced immediately before BeanContainerBuildItem in order to give recorders the chance to do something immediately before real recording steps come into play.

This build item instructs ArC to produce a ReflectiveClassBuildItem for a client proxy and intercepted subclass generated for the given bean class.