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