AnnotatedArrayType
, AnnotatedParameterizedType
, AnnotatedType
, AnnotatedTypeVariable
, AnnotatedWildcardType
, GenericDeclaration
, TypeVariable<D>
AccessibleObject
, Class
, Constructor
, Executable
, Field
, Method
, Module
, Package
, Parameter
, RecordComponent
public interface AnnotatedElement
AnnotatedType
interface and its subinterfaces are type annotations as the entity being potentially annotated is a type. Annotations returned by methods outside of the
AnnotatedType
hierarchy are declaration annotations. This interface allows annotations to be read reflectively. All annotations returned by methods in this interface are immutable and serializable. The arrays returned by methods of this interface may be modified by callers without affecting the arrays returned to other callers.
The getAnnotationsByType(Class)
and getDeclaredAnnotationsByType(Class)
methods support multiple annotations of the same type on an element. If the argument to either method is a repeatable annotation type (JLS 9.6), then the method will "look through" a container annotation (JLS 9.7), if present, and return any annotations inside the container. Container annotations may be generated at compile-time to wrap multiple annotations of the argument type.
The terms directly present, indirectly present, present, and associated are used throughout this interface to describe precisely which annotations are returned by methods:
RuntimeVisibleAnnotations
or
RuntimeVisibleParameterAnnotations
or
RuntimeVisibleTypeAnnotations
attribute, and the attribute contains A. RuntimeVisibleAnnotations
or RuntimeVisibleParameterAnnotations
or RuntimeVisibleTypeAnnotations
attribute, and A 's type is repeatable, and the attribute contains exactly one annotation whose value element contains A and whose type is the containing annotation type of A 's type. The table below summarizes which kind of annotation presence different methods in this interface examine.
Method | Kind of Presence | ||||
---|---|---|---|---|---|
Return Type | Signature | Directly Present | Indirectly Present | Present | Associated |
T |
getAnnotation(Class<T>) |
X | |||
Annotation[] |
getAnnotations() |
X | |||
T[] |
getAnnotationsByType(Class<T>) |
X | |||
T |
getDeclaredAnnotation(Class<T>) |
X | |||
Annotation[] |
getDeclaredAnnotations() |
X | |||
T[] |
getDeclaredAnnotationsByType(Class<T>) |
X | X |
For an invocation of get[Declared]AnnotationsByType(Class <T>)
, the order of annotations which are directly or indirectly present on an element E is computed as if indirectly present annotations on E are directly present on E in place of their container annotation, in the order in which they appear in the value element of the container annotation.
There are several compatibility concerns to keep in mind if an annotation type T is originally not repeatable and later modified to be repeatable. The containing annotation type for T is TC.
get[Declared]Annotation(Class<T>)
(called with an argument of T or TC) and
get[Declared]Annotations()
methods because the results of the methods will not change due to TC becoming the containing annotation type for T.
get[Declared]AnnotationsByType(Class<T>)
methods called with an argument of T, because those methods will now recognize an annotation of type TC as a container annotation for T and will "look through" it to expose annotations of type T. get[Declared]Annotation(Class<T>)
methods and
get[Declared]Annotations()
methods, because those methods will now only see a container annotation on the element and not see an annotation of type T. get[Declared]AnnotationsByType(Class<T>)
methods, because their results will expose the additional annotations of type T whereas previously they exposed only a single annotation of type T. If an annotation returned by a method in this interface contains (directly or indirectly) a Class
-valued member referring to a class that is not accessible in this VM, attempting to read the class by calling the relevant Class-returning method on the returned annotation will result in a TypeNotPresentException
.
Similarly, attempting to read an enum-valued member will result in a EnumConstantNotPresentException
if the enum constant in the annotation is no longer present in the enum class.
If an annotation type T is (meta-)annotated with an @Repeatable
annotation whose value element indicates a type TC, but TC does not declare a value()
method with a return type of T[]
, then an exception of type AnnotationFormatError
is thrown.
Finally, attempting to read a member whose definition has evolved incompatibly will result in a AnnotationTypeMismatchException
or an IncompleteAnnotationException
.
Modifier and Type | Method | Description |
---|---|---|
<T extends Annotation> |
getAnnotation |
Returns this element's annotation for the specified type if such an annotation is present, else null. |
Annotation[] |
getAnnotations() |
Returns annotations that are present on this element. |
default <T extends Annotation> |
getAnnotationsByType |
Returns annotations that are associated with this element. |
default <T extends Annotation> |
getDeclaredAnnotation |
Returns this element's annotation for the specified type if such an annotation is directly present, else null. |
Annotation[] |
getDeclaredAnnotations() |
Returns annotations that are directly present on this element. |
default <T extends Annotation> |
getDeclaredAnnotationsByType |
Returns this element's annotation(s) for the specified type if such annotations are either directly present or indirectly present. |
default boolean |
isAnnotationPresent |
Returns true if an annotation for the specified type is present on this element, else false. |
default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
The truth value returned by this method is equivalent to: getAnnotation(annotationClass) != null
getAnnotation(annotationClass) != null
.annotationClass
- the Class object corresponding to the annotation typeNullPointerException
- if the given annotation class is null<T extends Annotation> T getAnnotation(Class<T> annotationClass)
T
- the type of the annotation to query for and return if presentannotationClass
- the Class object corresponding to the annotation typeNullPointerException
- if the given annotation class is nullAnnotation[] getAnnotations()
default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass)
getAnnotation(Class)
is that this method detects if its argument is a repeatable annotation type (JLS 9.6), and if so, attempts to find one or more annotations of that type by "looking through" a container annotation. The caller of this method is free to modify the returned array; it will have no effect on the arrays returned to other callers.getDeclaredAnnotationsByType(Class)
passing
annotationClass
as the argument. If the returned array has length greater than zero, the array is returned. If the returned array is zero-length and this AnnotatedElement
is a class and the argument type is an inheritable annotation type, and the superclass of this AnnotatedElement
is non-null, then the returned result is the result of calling getAnnotationsByType(Class)
on the superclass with
annotationClass
as the argument. Otherwise, a zero-length array is returned.T
- the type of the annotation to query for and return if presentannotationClass
- the Class object corresponding to the annotation typeNullPointerException
- if the given annotation class is nulldefault <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)
getDeclaredAnnotations()
returning the first annotation whose annotation type matches the argument type.T
- the type of the annotation to query for and return if directly presentannotationClass
- the Class object corresponding to the annotation typeNullPointerException
- if the given annotation class is nulldefault <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass)
getDeclaredAnnotation(Class)
is that this method detects if its argument is a repeatable annotation type (JLS 9.6), and if so, attempts to find one or more annotations of that type by "looking through" a container annotation if one is present. The caller of this method is free to modify the returned array; it will have no effect on the arrays returned to other callers.getDeclaredAnnotation(Class)
one or more times to find a directly present annotation and, if the annotation type is repeatable, to find a container annotation. If annotations of the annotation type annotationClass
are found to be both directly and indirectly present, then getDeclaredAnnotations()
will get called to determine the order of the elements in the returned array. Alternatively, the default implementation may call getDeclaredAnnotations()
a single time and the returned array examined for both directly and indirectly present annotations. The results of calling getDeclaredAnnotations()
are assumed to be consistent with the results of calling getDeclaredAnnotation(Class)
.
T
- the type of the annotation to query for and return if directly or indirectly presentannotationClass
- the Class object corresponding to the annotation typeNullPointerException
- if the given annotation class is nullAnnotation[] getDeclaredAnnotations()
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/reflect/AnnotatedElement.html