# Print output for @column tags ?>
public
interface
AnnotatedElement
java.lang.reflect.AnnotatedElement |
Represents an annotated element of the program currently running in this VM. 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.
Android note: methods that return multiple annotations of different types such as
getAnnotations()
and getDeclaredAnnotations()
can be affected
by the explicit character-code ordering of annotations types specified by the DEX format.
Annotations of different types on a single element are not guaranteed to be returned in the order
they are declared in source.
The getAnnotationsByType(java.lang.Class)
and getDeclaredAnnotationsByType(java.lang.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:
The table below summarizes which kind of annotation presence different methods in this interface examine.
Kind of Presence | |||||
---|---|---|---|---|---|
Method | 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 type.
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
.
See also:
Public methods | |
---|---|
abstract
<T extends Annotation>
T
|
getAnnotation(Class<T> annotationClass)
Returns this element's annotation for the specified type if such an annotation is present, else null. |
abstract
Annotation[]
|
getAnnotations()
Returns annotations that are present on this element. |
default
<T extends Annotation>
T[]
|
getAnnotationsByType(Class<T> annotationClass)
Returns annotations that are associated with this element. |
default
<T extends Annotation>
T
|
getDeclaredAnnotation(Class<T> annotationClass)
Returns this element's annotation for the specified type if such an annotation is directly present, else null. |
abstract
Annotation[]
|
getDeclaredAnnotations()
Returns annotations that are directly present on this element. |
default
<T extends Annotation>
T[]
|
getDeclaredAnnotationsByType(Class<T> annotationClass)
Returns this element's annotation(s) for the specified type if such annotations are either directly present or indirectly present. |
default
boolean
|
isAnnotationPresent(Class<? extends Annotation> annotationClass)
Returns true if an annotation for the specified type is present on this element, else false. |
public abstract T getAnnotation (Class<T> annotationClass)
Returns this element's annotation for the specified type if such an annotation is present, else null.
Parameters | |
---|---|
annotationClass |
Class : the Class object corresponding to the
annotation type |
Returns | |
---|---|
T |
this element's annotation for the specified annotation type if present on this element, else null |
Throws | |
---|---|
NullPointerException |
if the given annotation class is null |
public abstract Annotation[] getAnnotations ()
Returns annotations that are present on this element. If there are no annotations present on this element, the return value is an array of length 0. The caller of this method is free to modify the returned array; it will have no effect on the arrays returned to other callers.
Returns | |
---|---|
Annotation[] |
annotations present on this element |
public T[] getAnnotationsByType (Class<T> annotationClass)
Returns annotations that are associated with this element.
If there are no annotations associated with this element, the return
value is an array of length 0.
The difference between this method and getAnnotation(java.lang.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(java.lang.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(java.lang.Class)
on the superclass with annotationClass
as the argument. Otherwise, a zero-length
array is returned.Parameters | |
---|---|
annotationClass |
Class : the Class object corresponding to the
annotation type |
Returns | |
---|---|
T[] |
all this element's annotations for the specified annotation type if associated with this element, else an array of length zero |
Throws | |
---|---|
NullPointerException |
if the given annotation class is null |
public T getDeclaredAnnotation (Class<T> annotationClass)
Returns this element's annotation for the specified type if such an annotation is directly present, else null. This method ignores inherited annotations. (Returns null if no annotations are directly present on this element.)
getDeclaredAnnotations()
returning the first annotation whose
annotation type matches the argument type.Parameters | |
---|---|
annotationClass |
Class : the Class object corresponding to the
annotation type |
Returns | |
---|---|
T |
this element's annotation for the specified annotation type if directly present on this element, else null |
Throws | |
---|---|
NullPointerException |
if the given annotation class is null |
public abstract Annotation[] getDeclaredAnnotations ()
Returns annotations that are directly present on this element. This method ignores inherited annotations. If there are no annotations directly present on this element, the return value is an array of length 0. The caller of this method is free to modify the returned array; it will have no effect on the arrays returned to other callers.
Returns | |
---|---|
Annotation[] |
annotations directly present on this element |
public T[] getDeclaredAnnotationsByType (Class<T> annotationClass)
Returns this element's annotation(s) for the specified type if
such annotations are either directly present or
indirectly present. This method ignores inherited
annotations.
If there are no specified annotations directly or indirectly
present on this element, the return value is an array of length
0.
The difference between this method and getDeclaredAnnotation(java.lang.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(java.lang.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(java.lang.Class)
.
Parameters | |
---|---|
annotationClass |
Class : the Class object corresponding to the
annotation type |
Returns | |
---|---|
T[] |
all this element's annotations for the specified annotation type if directly or indirectly present on this element, else an array of length zero |
Throws | |
---|---|
NullPointerException |
if the given annotation class is null |
public boolean isAnnotationPresent (Class<? extends Annotation> annotationClass)
Returns true if an annotation for the specified type is present on this element, else false. This method is designed primarily for convenient access to marker annotations.
The truth value returned by this method is equivalent to:
getAnnotation(annotationClass) != null
The body of the default method is specified to be the code above.
Parameters | |
---|---|
annotationClass |
Class : the Class object corresponding to the
annotation type |
Returns | |
---|---|
boolean |
true if an annotation for the specified annotation type is present on this element, else false |
Throws | |
---|---|
NullPointerException |
if the given annotation class is null |