Debian Codegraph @

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

raw
1 package jakarta.enterprise.lang.model;
2
3 import jakarta.enterprise.lang.model.declarations.ClassInfo;
4 import jakarta.enterprise.lang.model.types.Type;
5
6 import java.util.List;
7
8 /**
9 * The value of an annotation member. Annotation member values are of several kinds:
10 * <ul>
11 * <li>primitive constants;</li>
12 * <li>{@link String} constants;</li>
13 * <li>{@link Enum} constants;</li>
14 * <li>{@link Class} literals;</li>
15 * <li>nested {@link java.lang.annotation.Annotation Annotation}s;</li>
16 * <li>arrays of previously mentioned types.</li>
17 * </ul>
18 * The {@link #kind()} method returns the kind of this annotation member value. The {@code is*} methods
19 * (such as {@link #isBoolean()}) allow checking if this annotation member value is of given kind.
20 * The {@code as*} methods (such as {@link #asBoolean()}) allow "unwrapping" this annotation member value,
21 * if it is of the corresponding kind.
22 * <p>
23 * Note that the {@code as*} methods do not perform type conversion, so if this annotation member value
24 * is an {@code int}, calling {@code asLong()} will throw an exception.
25 * <p>
26 * Implementations of this interface are required to define the {@code equals} and {@code hashCode} methods.
27 * Implementations of this interface are encouraged to define the {@code toString} method such that
28 * it returns a text resembling the corresponding Java&trade; syntax.
29 * <p>
30 * There is no guarantee that any particular annotation member, represented by an implementation of this interface,
31 * will always be represented by the same object. This includes natural singletons such as {@code boolean} values.
32 * Instances should always be compared using {@code equals}.
33 *
34 * @since 4.0
35 */
36 public interface AnnotationMember {
37 /**
38 * Name of the commonly used {@code value()} annotation member.
39 */
40 String VALUE = "value";
41
42 /**
43 * The kind of the annotation member value.
44 */
45 enum Kind {
46 /**
47 * A primitive {@code boolean} value.
48 */
49 BOOLEAN,
50 /**
51 * A primitive {@code byte} value.
52 */
53 BYTE,
54 /**
55 * A primitive {@code short} value.
56 */
57 SHORT,
58 /**
59 * A primitive {@code int} value.
60 */
61 INT,
62 /**
63 * A primitive {@code long} value.
64 */
65 LONG,
66 /**
67 * A primitive {@code float} value.
68 */
69 FLOAT,
70 /**
71 * A primitive {@code double} value.
72 */
73 DOUBLE,
74 /**
75 * A primitive {@code char} value.
76 */
77 CHAR,
78 /**
79 * A {@link String} value.
80 */
81 STRING,
82 /**
83 * An {@link Enum} value.
84 */
85 ENUM,
86 /**
87 * A {@link Class} value. Represented as {@link Type}.
88 */
89 CLASS,
90 /**
91 * A nested {@link java.lang.annotation.Annotation Annotation} value.
92 * Represented as {@link AnnotationInfo}.
93 */
94 NESTED_ANNOTATION,
95 /**
96 * An array value.
97 */
98 ARRAY,
99 }
100
101 /**
102 * Returns the kind of this annotation member value.
103 *
104 * @return the kind of this annotation member value, never {@code null}
105 */
106 Kind kind();
107
108 /**
109 * @return {@code true} if the kind is a {@code boolean}, {@code false} otherwise
110 */
111 default boolean isBoolean() {
112 return kind() == Kind.BOOLEAN;
113 }
114
115 /**
116 * @return {@code true} if the kind is a {@code byte}, {@code false} otherwise
117 */
118 default boolean isByte() {
119 return kind() == Kind.BYTE;
120 }
121
122 /**
123 * @return {@code true} if the kind is a {@code short}, {@code false} otherwise
124 */
125 default boolean isShort() {
126 return kind() == Kind.SHORT;
127 }
128
129 /**
130 * @return {@code true} if the kind is an {@code int}, {@code false} otherwise
131 */
132 default boolean isInt() {
133 return kind() == Kind.INT;
134 }
135
136 /**
137 * @return {@code true} if the kind is a {@code long}, {@code false} otherwise
138 */
139 default boolean isLong() {
140 return kind() == Kind.LONG;
141 }
142
143 /**
144 * @return {@code true} if the kind is a {@code float}, {@code false} otherwise
145 */
146 default boolean isFloat() {
147 return kind() == Kind.FLOAT;
148 }
149
150 /**
151 * @return {@code true} if the kind is a {@code double}, {@code false} otherwise
152 */
153 default boolean isDouble() {
154 return kind() == Kind.DOUBLE;
155 }
156
157 /**
158 * @return {@code true} if the kind is a {@code char}, {@code false} otherwise
159 */
160 default boolean isChar() {
161 return kind() == Kind.CHAR;
162 }
163
164 /**
165 * @return {@code true} if the kind is a {@link String}, {@code false} otherwise
166 */
167 default boolean isString() {
168 return kind() == Kind.STRING;
169 }
170
171 /**
172 * @return {@code true} if the kind is an {@link Enum}, {@code false} otherwise
173 */
174 default boolean isEnum() {
175 return kind() == Kind.ENUM;
176 }
177
178 /**
179 * @return {@code true} if the kind is a {@link Class}, {@code false} otherwise
180 */
181 default boolean isClass() {
182 return kind() == Kind.CLASS;
183 }
184
185 /**
186 * @return {@code true} if the kind is a nested {@link java.lang.annotation.Annotation Annotation}, {@code false} otherwise
187 */
188 default boolean isNestedAnnotation() {
189 return kind() == Kind.NESTED_ANNOTATION;
190 }
191
192 /**
193 * @return {@code true} if the kind is an array, {@code false} otherwise
194 */
195 default boolean isArray() {
196 return kind() == Kind.ARRAY;
197 }
198
199 /**
200 * Returns this value as a {@code boolean}.
201 *
202 * @return the boolean value
203 * @throws IllegalStateException if this annotation member value is not a {@code boolean}
204 */
205 boolean asBoolean();
206
207 /**
208 * Returns this value as a {@code byte}.
209 *
210 * @return the byte value
211 * @throws IllegalStateException if this annotation member value is not a {@code byte}
212 */
213 byte asByte();
214
215 /**
216 * Returns this value as a {@code short}.
217 *
218 * @return the short value
219 * @throws IllegalStateException if this annotation member value is not a {@code short}
220 */
221 short asShort();
222
223 /**
224 * Returns this value as an {@code int}.
225 *
226 * @return the int value
227 * @throws IllegalStateException if this annotation member value is not an {@code int}
228 */
229 int asInt();
230
231 /**
232 * Returns this value as a {@code long}.
233 *
234 * @return the long value
235 * @throws IllegalStateException if this annotation member value is not a {@code long}
236 */
237 long asLong();
238
239 /**
240 * Returns this value as a {@code float}.
241 *
242 * @return the float value
243 * @throws IllegalStateException if this annotation member value is not a {@code float}
244 */
245 float asFloat();
246
247 /**
248 * Returns this value as a {@code double}.
249 *
250 * @return the double value
251 * @throws IllegalStateException if this annotation member value is not a {@code double}
252 */
253 double asDouble();
254
255 /**
256 * Returns this value as a {@code char}.
257 *
258 * @return the char value
259 * @throws IllegalStateException if this annotation member value is not a {@code char}
260 */
261 char asChar();
262
263 /**
264 * Returns this value as a {@code String}.
265 *
266 * @return the String value
267 * @throws IllegalStateException if this annotation member value is not a {@code String}
268 */
269 String asString();
270
271 /**
272 * Returns this enum value as an instance of the enum type.
273 *
274 * @param enumType the enum type
275 * @param <E> the enum generic type
276 * @return the enum instance
277 * @throws IllegalArgumentException if given {@code enumType} is not an enum type
278 * @throws IllegalStateException if this annotation member value is not an enum value
279 */
280 <E extends Enum<E>> E asEnum(Class<E> enumType);
281
282 /**
283 * Returns the type of this enum value.
284 *
285 * @return a {@link ClassInfo} representing the enum type
286 * @throws IllegalStateException if this annotation member value is not an enum value
287 */
288 ClassInfo asEnumClass();
289
290 /**
291 * Returns the name of this enum value.
292 *
293 * @return the name of this enum value
294 * @throws IllegalStateException if this annotation member value is not an enum value
295 */
296 String asEnumConstant();
297
298 /**
299 * Returns this class value as a {@link Type}. It can be:
300 * <ul>
301 * <li>the {@linkplain jakarta.enterprise.lang.model.types.VoidType void} pseudo-type;</li>
302 * <li>a {@linkplain jakarta.enterprise.lang.model.types.PrimitiveType primitive} type;</li>
303 * <li>a {@linkplain jakarta.enterprise.lang.model.types.ClassType class} type;</li>
304 * <li>an {@linkplain jakarta.enterprise.lang.model.types.ArrayType array} type, whose element type
305 * is a primitive type or a class type.</li>
306 * </ul>
307 *
308 * @return the class value, as a {@link Type}
309 * @throws IllegalStateException if this annotation member value is not a class value
310 */
311 Type asType();
312
313 /**
314 * Returns this nested annotation value as an {@link AnnotationInfo}.
315 *
316 * @return an {@link AnnotationInfo} instance
317 * @throws IllegalStateException if this annotation member value is not a nested annotation
318 */
319 AnnotationInfo asNestedAnnotation();
320
321 /**
322 * Returns this array value as an immutable {@link List} of {@link AnnotationMember}s.
323 * Returns an empty list if the array is empty.
324 *
325 * @return an immutable list of {@link AnnotationMember}s
326 * @throws IllegalStateException if this annotation member value is not an array
327 */
328 List<AnnotationMember> asArray();
329 }