public interface BuildCompatibleExtension

Build compatible extensions are service providers for this interface, as defined in ServiceLoader. This means: they are classes that implement this interface, provide a META-INF/services file, and satisfy all other service provider constraints. Additionally, build compatible extensions must not be beans and must not be referred to by application code.

Build compatible extensions may define arbitrary public, non-static, void-returning methods without type parameters, annotated with one of the extension annotations. Such methods are called extension methods.

Extension methods are executed in 5 phases, corresponding to 5 extension annotations:

• @Discovery
• @Enhancement
• @Registration
• @Synthesis
• @Validation

Extension methods may declare arbitrary number of parameters. In each execution phase, different types of parameters may be declared, as documented in the corresponding extension annotation. All the parameters will be provided by the container when the extension method is invoked. If an extension method declares a parameter of a type unsupported in the execution phase, the container treats it as a deployment problem.

Extension methods may be assigned a priority using @Priority. Extension methods with smaller priority values are invoked first. Extension methods without specified priority have a default priority of Priority.APPLICATION + 500. If two extension methods have equal priority, the ordering between them is undefined. Note that priority only affects order of extension methods in a single phase.

For each build compatible extension, the container creates a single instance. All extension methods are invoked on the same instance.

When extension methods are invoked, a CDI container does not have to be running, so calling CDI.current() from an extension method, or attempting to access a running CDI container in any other way, results in non-portable behavior.

Build compatible extensions may be annotated @SkipIfPortableExtensionPresent when they are supposed to be ignored in presence of a given portable extension.

CDI implementations are not required to accept custom implementations of any jakarta.enterprise.lang.model or jakarta.enterprise.inject.build.compatible.spi interface. In other words, users may only use instances of these interfaces that they previously obtained from the corresponding API. If not, non-portable behavior results.

In build compatible extensions, implementations of AnnotationTarget only return annotations with the runtime retention policy.