Debian Codegraph @

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

raw
1 package jakarta.enterprise.lang.model;
2
3 import jakarta.enterprise.lang.model.declarations.ClassInfo;
4
5 import java.lang.annotation.Repeatable;
6 import java.util.Map;
7
8 /**
9 * An annotation instance, typically obtained from an {@link AnnotationTarget}.
10 * Provides access to annotation members and their values.
11 * <p>
12 * Implementations of this interface are required to define the {@code equals} and {@code hashCode} methods.
13 * Implementations of this interface are encouraged to define the {@code toString} method such that
14 * it returns a text resembling the corresponding Java&trade; syntax.
15 * <p>
16 * There is no guarantee that any particular annotation instance, represented by an implementation of this interface,
17 * will always be represented by the same object. That includes natural singletons such as the {@code jakarta.inject.Singleton}
18 * annotation. Instances should always be compared using {@code equals}.
19 *
20 * @since 4.0
21 */
22 public interface AnnotationInfo {
23 /**
24 * Returns the {@linkplain ClassInfo declaration} of this annotation's type.
25 *
26 * @return the {@linkplain ClassInfo declaration} of this annotation's type, never {@code null}
27 */
28 ClassInfo declaration();
29
30 /**
31 * Binary name of this annotation's type, as defined by <cite>The Java&trade; Language Specification</cite>;
32 * in other words, the annotation type name as returned by {@link Class#getName()}.
33 * Equivalent to {@code declaration().name()}.
34 *
35 * @return binary name of this annotation's type, never {@code null}
36 */
37 default String name() {
38 return declaration().name();
39 }
40
41 /**
42 * Returns whether this annotation is repeatable. In other words, returns whether
43 * this annotation's type is meta-annotated {@code @Repeatable}.
44 *
45 * @return whether this annotation is repeatable
46 */
47 default boolean isRepeatable() {
48 return declaration().hasAnnotation(Repeatable.class);
49 }
50
51 /**
52 * Returns whether this annotation has a member with given {@code name}.
53 *
54 * @param name member name, must not be {@code null}
55 * @return {@code true} if this annotation has a member with given {@code name}, {@code false} otherwise
56 */
57 boolean hasMember(String name);
58
59 /**
60 * Returns the {@linkplain AnnotationMember value} of this annotation's member with given {@code name}.
61 *
62 * @param name member name, must not be {@code null}
63 * @return value of this annotation's member with given {@code name} or {@code null} if such member does not exist
64 */
65 AnnotationMember member(String name);
66
67 /**
68 * Returns whether this annotation has the {@link AnnotationMember#VALUE value} member.
69 *
70 * @return {@code true} if this annotation has the {@link AnnotationMember#VALUE value} member, {@code false} otherwise
71 */
72 default boolean hasValue() {
73 return hasMember(AnnotationMember.VALUE);
74 }
75
76 /**
77 * Returns the {@linkplain AnnotationMember value} of this annotation's {@link AnnotationMember#VALUE value} member.
78 *
79 * @return value of this annotation's {@link AnnotationMember#VALUE value} member or {@code null} if the member does not exist
80 */
81 default AnnotationMember value() {
82 return member(AnnotationMember.VALUE);
83 }
84
85 /**
86 * Returns all members of this annotation as a map, where the key is the member name
87 * and the value is the member value. Returns an empty map if this annotation has no members.
88 *
89 * @return an immutable map of all members of this annotation, never {@code null}
90 */
91 Map<String, AnnotationMember> members();
92 }