Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Enhancement.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 import java.lang.annotation.Annotation;
14 import java.lang.annotation.ElementType;
15 import java.lang.annotation.Retention;
16 import java.lang.annotation.RetentionPolicy;
17 import java.lang.annotation.Target;
18
19 /**
20 * 2nd phase of {@linkplain BuildCompatibleExtension build compatible extension} execution.
21 * Allows transforming annotations.
22 * <p>
23 * In the following text, the term <em>expected types</em> denotes the set of types defined by
24 * the {@link #types() types}, {@link #withSubtypes() withSubtypes} and {@link #withAnnotations() withAnnotations}
25 * members of the {@code @Enhancement} annotation. The term <em>discovered types</em> denotes
26 * the subset of <em>expected types</em> that were discovered during type discovery.
27 * <p>
28 * Methods annotated {@code @Enhancement} must declare exactly one parameter of one of these types:
29 * <ul>
30 * <li>{@link ClassConfig} or {@link jakarta.enterprise.lang.model.declarations.ClassInfo ClassInfo}</li>
31 * <li>{@link MethodConfig} or {@link jakarta.enterprise.lang.model.declarations.MethodInfo MethodInfo}</li>
32 * <li>{@link FieldConfig} or {@link jakarta.enterprise.lang.model.declarations.FieldInfo FieldInfo}</li>
33 * </ul>
34 * If an {@code @Enhancement} method has a parameter of type {@code ClassConfig} or {@code ClassInfo},
35 * the method is called once for each <em>discovered type</em>.
36 * <p>
37 * If an {@code @Enhancement} method has a parameter of type {@code MethodConfig} or {@code MethodInfo},
38 * the method is called once for each constructor or method that is declared on each <em>discovered type</em>,
39 * as defined in {@link jakarta.enterprise.lang.model.declarations.ClassInfo#constructors() ClassInfo.constructors}
40 * and {@link jakarta.enterprise.lang.model.declarations.ClassInfo#methods() ClassInfo.methods}.
41 * <p>
42 * If an {@code @Enhancement} method has a parameter of type {@code FieldConfig} or {@code FieldInfo},
43 * the method is called once for each field that is declared on each <em>discovered type</em>, as defined
44 * in {@link jakarta.enterprise.lang.model.declarations.ClassInfo#fields() ClassInfo.fields}.
45 * <p>
46 * If the {@code @Enhancement} method doesn't declare any parameter of one of these types,
47 * or if it declares more than one, the container treats it as a definition error.
48 * <p>
49 * Additionally, methods annotated {@code @Enhancement} may declare parameters of these types:
50 * <ul>
51 * <li>{@link Messages}</li>
52 * <li>{@link Types}</li>
53 * </ul>
54 * <p>
55 * Finally, {@link AnnotationBuilder} may be used to create instances
56 * of {@link jakarta.enterprise.lang.model.AnnotationInfo AnnotationInfo}.
57 *
58 * @since 4.0
59 */
60 @Target(ElementType.METHOD)
61 @Retention(RetentionPolicy.RUNTIME)
62 public @interface Enhancement {
63 /**
64 * Defines the set of <em>expected types</em>. If {@link #withSubtypes() withSubtypes}
65 * is {@code true}, the set of <em>expected types</em> includes all direct and indirect
66 * subtypes of these types. If {@link #withAnnotations() withAnnotations} is defined,
67 * the set of <em>expected types</em> only includes types that use given annotations.
68 *
69 * @return the set of <em>expected types</em>
70 */
71 Class<?>[] types();
72
73 /**
74 * If {@code true}, the set of <em>expected types</em> includes all direct and
75 * indirect subtypes of given {@link #types() types}.
76 *
77 * @return whether subtypes should be included in the set of <em>expected types</em>
78 */
79 boolean withSubtypes() default false;
80
81 /**
82 * Narrows down the set of <em>expected types</em>, defined by {@link #types() types}
83 * and {@link #withSubtypes() withSubtypes}, to types that use any of given annotations.
84 * The annotation can appear on the type, or on any member of the type, or on any
85 * parameter of any member of the type, or as a meta-annotation on any annotation
86 * that is considered by these rules.
87 * <p>
88 * If empty, the set of <em>expected types</em> is not narrowed down in any way.
89 * If {@code java.lang.Annotation} is present, the set of <em>expected types</em>
90 * is narrowed down to types that use any annotation.
91 * <p>
92 * Defaults to an empty array, so that the set of <em>expected types</em> is not
93 * narrowed down in any way.
94 *
95 * @return types of annotations that must be present on the <em>expected types</em>
96 */
97 Class<? extends Annotation>[] withAnnotations() default {};
98 }