Debian Codegraph @

lang-model/src/main/java/jakarta/enterprise/lang/model/AnnotationTarget.java

raw
1 package jakarta.enterprise.lang.model;
2
3 import jakarta.enterprise.lang.model.declarations.DeclarationInfo;
4 import jakarta.enterprise.lang.model.types.Type;
5
6 import java.lang.annotation.Annotation;
7 import java.util.Collection;
8 import java.util.function.Predicate;
9
10 /**
11 * An annotation target is anything that can be annotated.
12 * That is:
13 *
14 * <ul>
15 * <li>a {@linkplain DeclarationInfo declaration}, such as a class, a method, a field, etc.</li>
16 * <li>a {@linkplain Type type}, such as the type of a method parameter, the type of a field, a type argument,
17 * a type parameter, present in a declaration of a generic class or method, etc.</li>
18 * </ul>
19 *
20 * The {@code hasAnnotation}, {@code annotation}, {@code repeatableAnnotation} and {@code annotations} methods
21 * may be used to obtain information about annotations present on this annotation target. The phrase
22 * "present on this annotation target" means: either the annotation is declared or implicitly declared
23 * directly on this annotation target, or this annotation target is a class declaration and the annotation is
24 * {@linkplain java.lang.annotation.Inherited inherited} from a superclass.
25 * <p>
26 * Note that if more than one annotation of a {@linkplain java.lang.annotation.Repeatable repeatable} annotation type
27 * is declared on an annotation target, only an implicitly declared <em>container annotation</em> is present
28 * on the annotation target; the originally declared annotations are not. If exactly one annotation of a repeatable
29 * annotation type is declared on an annotation target, that annotation is present.
30 * <p>
31 * Annotations are represented as {@link AnnotationInfo}, so that implementations of this interface are not required
32 * to instantiate the annotation type.
33 * <p>
34 * Implementations of this interface are required to define the {@code equals} and {@code hashCode} methods.
35 * Implementations of this interface are encouraged to define the {@code toString} method such that
36 * it returns a text resembling the corresponding Java&trade; syntax.
37 * <p>
38 * There is no guarantee that any particular construct, represented by an implementation of this interface,
39 * will always be represented by the same object. That includes natural singletons such as the {@code java.lang.Object}
40 * class declaration, or the {@code void} pseudo-type. Instances should always be compared using {@code equals}.
41 *
42 * @since 4.0
43 */
44 public interface AnnotationTarget {
45 /**
46 * Returns whether this annotation target is a {@linkplain DeclarationInfo declaration}.
47 *
48 * @return {@code true} if this is a declaration, {@code false} otherwise
49 */
50 boolean isDeclaration();
51
52 /**
53 * Returns whether this annotation target is a {@linkplain Type type}.
54 *
55 * @return {@code true} if this is a type, {@code false} otherwise
56 */
57 boolean isType();
58
59 /**
60 * Returns this annotation target as a {@linkplain DeclarationInfo declaration}.
61 *
62 * @return this declaration, never {@code null}
63 * @throws IllegalStateException if {@link #isDeclaration()} returns {@code false}
64 */
65 DeclarationInfo asDeclaration();
66
67 /**
68 * Returns this annotation target as a {@linkplain Type type}.
69 *
70 * @return this type, never {@code null}
71 * @throws IllegalStateException if {@link #isType()} returns {@code false}
72 */
73 Type asType();
74
75 /**
76 * Returns whether an annotation of given type is present on this annotation target.
77 *
78 * @param annotationType the annotation type, must not be {@code null}
79 * @return {@code true} if given annotation type is present on this annotation target, {@code false} otherwise
80 */
81 boolean hasAnnotation(Class<? extends Annotation> annotationType);
82
83 /**
84 * Returns whether given predicate matches any annotation present on this annotation target.
85 *
86 * @param predicate annotation predicate, must not be {@code null}
87 * @return {@code true} if given predicate matches any annotation present on this annotation target, {@code false} otherwise.
88 */
89 boolean hasAnnotation(Predicate<AnnotationInfo> predicate);
90
91 /**
92 * Returns an annotation of given type, if it is present on this annotation target.
93 * Returns {@code null} if no such annotation is present.
94 *
95 * @param annotationType the annotation type, must not be {@code null}
96 * @param <T> the annotation generic type
97 * @return the {@link AnnotationInfo} or {@code null} if no such annotation is present
98 */
99 <T extends Annotation> AnnotationInfo annotation(Class<T> annotationType);
100
101 /**
102 * Returns a collection of annotations of given {@linkplain java.lang.annotation.Repeatable repeatable}
103 * {@code annotationType} that are present on this annotation target. Returns an empty collection if
104 * no such annotation is present.
105 * <p>
106 * For the purpose of this method, annotations in the {@code value} member of a container annotation,
107 * as defined using {@link java.lang.annotation.Repeatable @Repeatable}, are considered to be present
108 * on the annotation target on which the container annotation is present.
109 *
110 * @param annotationType the {@code @Repeatable} annotation type, must not be {@code null}
111 * @param <T> the annotation generic type
112 * @return immutable collection of {@link AnnotationInfo}, never {@code null}
113 */
114 <T extends Annotation> Collection<AnnotationInfo> repeatableAnnotation(Class<T> annotationType);
115
116 /**
117 * Returns a collection of all annotations present on this annotation target that match given predicate.
118 * Returns an empty collection if no such annotation is present.
119 *
120 * @param predicate annotation predicate, must not be {@code null}
121 * @return immutable collection of {@link AnnotationInfo}, never {@code null}
122 */
123 Collection<AnnotationInfo> annotations(Predicate<AnnotationInfo> predicate);
124
125 /**
126 * Returns a collection of all annotations present on this annotation target.
127 * Returns an empty collection if no annotation is present.
128 *
129 * @return immutable collection of {@link AnnotationInfo}, never {@code null}
130 */
131 Collection<AnnotationInfo> annotations();
132 }