Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildCompatibleExtension.java

raw
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 }