21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.reflect;
27
28 import java.lang.annotation.Annotation;
29 import java.lang.annotation.AnnotationFormatError;
30 import java.lang.annotation.Repeatable;
31 import java.util.Arrays;
32 import java.util.LinkedHashMap;
33 import java.util.Map;
34 import java.util.Objects;
35 import java.util.function.Function;
36 import java.util.stream.Collectors;
37 import sun.reflect.annotation.AnnotationSupport;
38 import sun.reflect.annotation.AnnotationType;
39
40 /**
41 * Represents an annotated element of the program currently running in this
42 * VM. This interface allows annotations to be read reflectively. All
43 * annotations returned by methods in this interface are immutable and
44 * serializable. The arrays returned by methods of this interface may be modified
45 * by callers without affecting the arrays returned to other callers.
46 *
47 * <p>The {@link #getAnnotationsByType(Class)} and {@link
48 * #getDeclaredAnnotationsByType(Class)} methods support multiple
49 * annotations of the same type on an element. If the argument to
50 * either method is a repeatable annotation type (JLS 9.6), then the
51 * method will "look through" a container annotation (JLS 9.7), if
52 * present, and return any annotations inside the container. Container
53 * annotations may be generated at compile-time to wrap multiple
54 * annotations of the argument type.
55 *
56 * <p>The terms <em>directly present</em>, <em>indirectly present</em>,
57 * <em>present</em>, and <em>associated</em> are used throughout this
58 * interface to describe precisely which annotations are returned by
59 * methods:
60 *
61 * <ul>
62 *
63 * <li> An annotation <i>A</i> is <em>directly present</em> on an
64 * element <i>E</i> if <i>E</i> has a {@code
65 * RuntimeVisibleAnnotations} or {@code
66 * RuntimeVisibleParameterAnnotations} or {@code
67 * RuntimeVisibleTypeAnnotations} attribute, and the attribute
68 * contains <i>A</i>.
69 *
70 * <li>An annotation <i>A</i> is <em>indirectly present</em> on an
71 * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or
243 * java.lang.annotation.AnnotationTypeMismatchException} or an
244 * {@link java.lang.annotation.IncompleteAnnotationException}.
245 *
246 * @see java.lang.EnumConstantNotPresentException
247 * @see java.lang.TypeNotPresentException
248 * @see AnnotationFormatError
249 * @see java.lang.annotation.AnnotationTypeMismatchException
250 * @see java.lang.annotation.IncompleteAnnotationException
251 * @since 1.5
252 * @author Josh Bloch
253 */
254 public interface AnnotatedElement {
255 /**
256 * Returns true if an annotation for the specified type
257 * is <em>present</em> on this element, else false. This method
258 * is designed primarily for convenient access to marker annotations.
259 *
260 * <p>The truth value returned by this method is equivalent to:
261 * {@code getAnnotation(annotationClass) != null}
262 *
263 * <p>The body of the default method is specified to be the code
264 * above.
265 *
266 * @param annotationClass the Class object corresponding to the
267 * annotation type
268 * @return true if an annotation for the specified annotation
269 * type is present on this element, else false
270 * @throws NullPointerException if the given annotation class is null
271 * @since 1.5
272 */
273 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {
274 return getAnnotation(annotationClass) != null;
275 }
276
277 /**
278 * Returns this element's annotation for the specified type if
279 * such an annotation is <em>present</em>, else null.
280 *
281 * @param <T> the type of the annotation to query for and return if present
282 * @param annotationClass the Class object corresponding to the
283 * annotation type
284 * @return this element's annotation for the specified annotation type if
293 *
294 * If there are no annotations <em>present</em> on this element, the return
295 * value is an array of length 0.
296 *
297 * The caller of this method is free to modify the returned array; it will
298 * have no effect on the arrays returned to other callers.
299 *
300 * @return annotations present on this element
301 * @since 1.5
302 */
303 Annotation[] getAnnotations();
304
305 /**
306 * Returns annotations that are <em>associated</em> with this element.
307 *
308 * If there are no annotations <em>associated</em> with this element, the return
309 * value is an array of length 0.
310 *
311 * The difference between this method and {@link #getAnnotation(Class)}
312 * is that this method detects if its argument is a <em>repeatable
313 * annotation type</em> (JLS 9.6), and if so, attempts to find one or
314 * more annotations of that type by "looking through" a container
315 * annotation.
316 *
317 * The caller of this method is free to modify the returned array; it will
318 * have no effect on the arrays returned to other callers.
319 *
320 * @implSpec The default implementation first calls {@link
321 * #getDeclaredAnnotationsByType(Class)} passing {@code
322 * annotationClass} as the argument. If the returned array has
323 * length greater than zero, the array is returned. If the returned
324 * array is zero-length and this {@code AnnotatedElement} is a
325 * class and the argument type is an inheritable annotation type,
326 * and the superclass of this {@code AnnotatedElement} is non-null,
327 * then the returned result is the result of calling {@link
328 * #getAnnotationsByType(Class)} on the superclass with {@code
329 * annotationClass} as the argument. Otherwise, a zero-length
330 * array is returned.
331 *
332 * @param <T> the type of the annotation to query for and return if present
333 * @param annotationClass the Class object corresponding to the
389 // More robust to do a dynamic cast at runtime instead
390 // of compile-time only.
391 return annotationClass.cast(annotation);
392 }
393 }
394 return null;
395 }
396
397 /**
398 * Returns this element's annotation(s) for the specified type if
399 * such annotations are either <em>directly present</em> or
400 * <em>indirectly present</em>. This method ignores inherited
401 * annotations.
402 *
403 * If there are no specified annotations directly or indirectly
404 * present on this element, the return value is an array of length
405 * 0.
406 *
407 * The difference between this method and {@link
408 * #getDeclaredAnnotation(Class)} is that this method detects if its
409 * argument is a <em>repeatable annotation type</em> (JLS 9.6), and if so,
410 * attempts to find one or more annotations of that type by "looking
411 * through" a container annotation if one is present.
412 *
413 * The caller of this method is free to modify the returned array; it will
414 * have no effect on the arrays returned to other callers.
415 *
416 * @implSpec The default implementation may call {@link
417 * #getDeclaredAnnotation(Class)} one or more times to find a
418 * directly present annotation and, if the annotation type is
419 * repeatable, to find a container annotation. If annotations of
420 * the annotation type {@code annotationClass} are found to be both
421 * directly and indirectly present, then {@link
422 * #getDeclaredAnnotations()} will get called to determine the
423 * order of the elements in the returned array.
424 *
425 * <p>Alternatively, the default implementation may call {@link
426 * #getDeclaredAnnotations()} a single time and the returned array
427 * examined for both directly and indirectly present
428 * annotations. The results of calling {@link
429 * #getDeclaredAnnotations()} are assumed to be consistent with the
|
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.reflect;
27
28 import java.lang.annotation.Annotation;
29 import java.lang.annotation.AnnotationFormatError;
30 import java.lang.annotation.Repeatable;
31 import java.util.Arrays;
32 import java.util.LinkedHashMap;
33 import java.util.Map;
34 import java.util.Objects;
35 import java.util.function.Function;
36 import java.util.stream.Collectors;
37 import sun.reflect.annotation.AnnotationSupport;
38 import sun.reflect.annotation.AnnotationType;
39
40 /**
41 * Represents an annotated construct of the program currently running in this
42 * VM.
43 *
44 * A construct is either an element or a type. Annotations on an
45 * element are on a <em>declaration</em>, whereas annotations on a
46 * type are on a specific <em>use</em> of a type name.
47 *
48 * As defined by <cite>The Java™ Language Specification</cite>
49 * section {@jls 9.7.4}, an annotation on an element is a
50 * <em>declaration annotation</em> and an annotation on a type is a
51 * <em>type annotation</em>.
52 *
53 * Note that any annotations returned by methods on the {@link
54 * AnnotatedType AnnotatedType} interface and its subinterfaces are
55 * type annotations as the entity being potentially annotated is a
56 * type. Annotations returned by methods outside of the {@code
57 * AnnotatedType} hierarchy are declaration annotations.
58 *
59 * <p>This interface allows annotations to be read reflectively. All
60 * annotations returned by methods in this interface are immutable and
61 * serializable. The arrays returned by methods of this interface may be modified
62 * by callers without affecting the arrays returned to other callers.
63 *
64 * <p>The {@link #getAnnotationsByType(Class)} and {@link
65 * #getDeclaredAnnotationsByType(Class)} methods support multiple
66 * annotations of the same type on an element. If the argument to
67 * either method is a repeatable annotation type (JLS {@jls 9.6}), then the
68 * method will "look through" a container annotation (JLS {@jls 9.7}), if
69 * present, and return any annotations inside the container. Container
70 * annotations may be generated at compile-time to wrap multiple
71 * annotations of the argument type.
72 *
73 * <p>The terms <em>directly present</em>, <em>indirectly present</em>,
74 * <em>present</em>, and <em>associated</em> are used throughout this
75 * interface to describe precisely which annotations are returned by
76 * methods:
77 *
78 * <ul>
79 *
80 * <li> An annotation <i>A</i> is <em>directly present</em> on an
81 * element <i>E</i> if <i>E</i> has a {@code
82 * RuntimeVisibleAnnotations} or {@code
83 * RuntimeVisibleParameterAnnotations} or {@code
84 * RuntimeVisibleTypeAnnotations} attribute, and the attribute
85 * contains <i>A</i>.
86 *
87 * <li>An annotation <i>A</i> is <em>indirectly present</em> on an
88 * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or
260 * java.lang.annotation.AnnotationTypeMismatchException} or an
261 * {@link java.lang.annotation.IncompleteAnnotationException}.
262 *
263 * @see java.lang.EnumConstantNotPresentException
264 * @see java.lang.TypeNotPresentException
265 * @see AnnotationFormatError
266 * @see java.lang.annotation.AnnotationTypeMismatchException
267 * @see java.lang.annotation.IncompleteAnnotationException
268 * @since 1.5
269 * @author Josh Bloch
270 */
271 public interface AnnotatedElement {
272 /**
273 * Returns true if an annotation for the specified type
274 * is <em>present</em> on this element, else false. This method
275 * is designed primarily for convenient access to marker annotations.
276 *
277 * <p>The truth value returned by this method is equivalent to:
278 * {@code getAnnotation(annotationClass) != null}
279 *
280 * @implSpec The body of the default method is specified to be returning the the value of the code
281 * expression above.
282 *
283 * @param annotationClass the Class object corresponding to the
284 * annotation type
285 * @return true if an annotation for the specified annotation
286 * type is present on this element, else false
287 * @throws NullPointerException if the given annotation class is null
288 * @since 1.5
289 */
290 default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {
291 return getAnnotation(annotationClass) != null;
292 }
293
294 /**
295 * Returns this element's annotation for the specified type if
296 * such an annotation is <em>present</em>, else null.
297 *
298 * @param <T> the type of the annotation to query for and return if present
299 * @param annotationClass the Class object corresponding to the
300 * annotation type
301 * @return this element's annotation for the specified annotation type if
310 *
311 * If there are no annotations <em>present</em> on this element, the return
312 * value is an array of length 0.
313 *
314 * The caller of this method is free to modify the returned array; it will
315 * have no effect on the arrays returned to other callers.
316 *
317 * @return annotations present on this element
318 * @since 1.5
319 */
320 Annotation[] getAnnotations();
321
322 /**
323 * Returns annotations that are <em>associated</em> with this element.
324 *
325 * If there are no annotations <em>associated</em> with this element, the return
326 * value is an array of length 0.
327 *
328 * The difference between this method and {@link #getAnnotation(Class)}
329 * is that this method detects if its argument is a <em>repeatable
330 * annotation type</em> (JLS {@jls 9.6}), and if so, attempts to find one or
331 * more annotations of that type by "looking through" a container
332 * annotation.
333 *
334 * The caller of this method is free to modify the returned array; it will
335 * have no effect on the arrays returned to other callers.
336 *
337 * @implSpec The default implementation first calls {@link
338 * #getDeclaredAnnotationsByType(Class)} passing {@code
339 * annotationClass} as the argument. If the returned array has
340 * length greater than zero, the array is returned. If the returned
341 * array is zero-length and this {@code AnnotatedElement} is a
342 * class and the argument type is an inheritable annotation type,
343 * and the superclass of this {@code AnnotatedElement} is non-null,
344 * then the returned result is the result of calling {@link
345 * #getAnnotationsByType(Class)} on the superclass with {@code
346 * annotationClass} as the argument. Otherwise, a zero-length
347 * array is returned.
348 *
349 * @param <T> the type of the annotation to query for and return if present
350 * @param annotationClass the Class object corresponding to the
406 // More robust to do a dynamic cast at runtime instead
407 // of compile-time only.
408 return annotationClass.cast(annotation);
409 }
410 }
411 return null;
412 }
413
414 /**
415 * Returns this element's annotation(s) for the specified type if
416 * such annotations are either <em>directly present</em> or
417 * <em>indirectly present</em>. This method ignores inherited
418 * annotations.
419 *
420 * If there are no specified annotations directly or indirectly
421 * present on this element, the return value is an array of length
422 * 0.
423 *
424 * The difference between this method and {@link
425 * #getDeclaredAnnotation(Class)} is that this method detects if its
426 * argument is a <em>repeatable annotation type</em> (JLS {@jls 9.6}), and if so,
427 * attempts to find one or more annotations of that type by "looking
428 * through" a container annotation if one is present.
429 *
430 * The caller of this method is free to modify the returned array; it will
431 * have no effect on the arrays returned to other callers.
432 *
433 * @implSpec The default implementation may call {@link
434 * #getDeclaredAnnotation(Class)} one or more times to find a
435 * directly present annotation and, if the annotation type is
436 * repeatable, to find a container annotation. If annotations of
437 * the annotation type {@code annotationClass} are found to be both
438 * directly and indirectly present, then {@link
439 * #getDeclaredAnnotations()} will get called to determine the
440 * order of the elements in the returned array.
441 *
442 * <p>Alternatively, the default implementation may call {@link
443 * #getDeclaredAnnotations()} a single time and the returned array
444 * examined for both directly and indirectly present
445 * annotations. The results of calling {@link
446 * #getDeclaredAnnotations()} are assumed to be consistent with the
|