| 1 |
/* |
| 2 |
* Copyright (c) 2021 Red Hat and others |
| 3 |
* |
| 4 |
* This program and the accompanying materials are made available under the |
| 5 |
* Apache Software License 2.0 which is available at: |
| 6 |
* https://www.apache.org/licenses/LICENSE-2.0. |
| 7 |
* |
| 8 |
* SPDX-License-Identifier: Apache-2.0 |
| 9 |
*/ |
| 10 |
|
| 11 |
package jakarta.enterprise.inject.build.compatible.spi; |
| 12 |
|
| 13 |
/** |
| 14 |
* Build compatible extensions are service providers for this interface, as defined in {@link java.util.ServiceLoader}. |
| 15 |
* This means: they are classes that implement this interface, provide a {@code META-INF/services} file, |
| 16 |
* and satisfy all other service provider constraints. Additionally, build compatible extensions must not be beans |
| 17 |
* and must not be referred to by application code. |
| 18 |
* <p> |
| 19 |
* Build compatible extensions may define arbitrary {@code public}, non-{@code static}, {@code void}-returning methods |
| 20 |
* without type parameters, annotated with one of the extension annotations. Such methods are called extension methods. |
| 21 |
* <p> |
| 22 |
* Extension methods are executed in 5 phases, corresponding to 5 extension annotations: |
| 23 |
* <ul> |
| 24 |
* <li>{@link Discovery @Discovery}</li> |
| 25 |
* <li>{@link Enhancement @Enhancement}</li> |
| 26 |
* <li>{@link Registration @Registration}</li> |
| 27 |
* <li>{@link Synthesis @Synthesis}</li> |
| 28 |
* <li>{@link Validation @Validation}</li> |
| 29 |
* </ul> |
| 30 |
* <p> |
| 31 |
* Extension methods may declare arbitrary number of parameters. In each execution phase, different types |
| 32 |
* of parameters may be declared, as documented in the corresponding extension annotation. All the parameters |
| 33 |
* will be provided by the container when the extension method is invoked. If an extension method declares |
| 34 |
* a parameter of a type unsupported in the execution phase, the container treats it as a deployment problem. |
| 35 |
* <p> |
| 36 |
* Extension methods may be assigned a priority using {@link jakarta.annotation.Priority @Priority}. |
| 37 |
* Extension methods with smaller priority values are invoked first. Extension methods without specified priority |
| 38 |
* have a default priority of {@link jakarta.interceptor.Interceptor.Priority#APPLICATION Priority.APPLICATION} + 500. |
| 39 |
* If two extension methods have equal priority, the ordering between them is undefined. Note that priority |
| 40 |
* only affects order of extension methods in a single phase. |
| 41 |
* <p> |
| 42 |
* For each build compatible extension, the container creates a single instance. All extension methods |
| 43 |
* are invoked on the same instance. |
| 44 |
* <p> |
| 45 |
* When extension methods are invoked, a CDI container does not have to be running, so calling {@code CDI.current()} |
| 46 |
* from an extension method, or attempting to access a running CDI container in any other way, results in |
| 47 |
* non-portable behavior. |
| 48 |
* <p> |
| 49 |
* Build compatible extensions may be annotated {@link SkipIfPortableExtensionPresent @SkipIfPortableExtensionPresent} |
| 50 |
* when they are supposed to be ignored in presence of a given portable extension. |
| 51 |
* <p> |
| 52 |
* CDI implementations are not required to accept custom implementations of any {@code jakarta.enterprise.lang.model} |
| 53 |
* or {@code jakarta.enterprise.inject.build.compatible.spi} interface. In other words, users may only use instances |
| 54 |
* of these interfaces that they previously obtained from the corresponding API. If not, non-portable behavior results. |
| 55 |
* <p> |
| 56 |
* In build compatible extensions, implementations of {@link jakarta.enterprise.lang.model.AnnotationTarget} |
| 57 |
* only return annotations with the {@linkplain java.lang.annotation.RetentionPolicy#RUNTIME runtime} retention policy. |
| 58 |
* |
| 59 |
* @since 4.0 |
| 60 |
*/ |
| 61 |
public interface BuildCompatibleExtension { |
| 62 |
} |