Interface AnnotatedElement

All Known Subinterfaces:
AnnotatedArrayType,AnnotatedParameterizedType,AnnotatedType,AnnotatedTypeVariable,AnnotatedWildcardType,GenericDeclaration,TypeVariable<D>
All Known Implementing Classes:
AccessibleObject,Class,Constructor,Executable,Field,Method,Module,Package,Parameter,RecordComponent
public interfaceAnnotatedElement
Represents an annotated construct of the program currently running in this VM. A construct is either an element or a type. Annotations on an element are on adeclaration, whereas annotations on a type are on a specificuse of a type name. As defined byThe Java Language Specification section9.7.4, an annotation on an element is adeclaration annotation and an annotation on a type is atype annotation. Note that any annotations returned by methods on theAnnotatedType 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.

ThegetAnnotationsByType(Class) andgetDeclaredAnnotationsByType(Class) methods support multiple annotations of the same type on an element. If the argument to either method is a repeatable annotation type (JLS9.6), then the method will "look through" a container annotation (JLS9.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 termsdirectly present,indirectly present,present, andassociated are used throughout this interface to describe precisely which annotations are returned by methods:

  • An annotationA isdirectly present on an elementE ifE has a RuntimeVisibleAnnotations or RuntimeVisibleParameterAnnotations or RuntimeVisibleTypeAnnotations attribute, and the attribute containsA.
  • An annotationA isindirectly present on an elementE ifE has aRuntimeVisibleAnnotations orRuntimeVisibleParameterAnnotations orRuntimeVisibleTypeAnnotations attribute, andA 's type is repeatable, and the attribute contains exactly one annotation whose value element containsA and whose type is the containing annotation type ofA 's type.
  • An annotationA ispresent on an elementE if either:
    • A is directly present onE; or
    • No annotation ofA 's type is directly present onE, andE is a class, andA 's type is inheritable, andA is present on the superclass ofE.
  • An annotationA isassociated with an elementE if either:
    • A is directly or indirectly present onE; or
    • No annotation ofA 's type is directly or indirectly present onE, andE is a class, andA's type is inheritable, andA is associated with the superclass ofE.

The table below summarizes which kind of annotation presence different methods in this interface examine.

Overview of kind of presence detected by different AnnotatedElement methods
MethodKind of Presence
Return TypeSignatureDirectly PresentIndirectly PresentPresentAssociated
TgetAnnotation(Class<T>)X
Annotation[]getAnnotations()X
T[]getAnnotationsByType(Class<T>)X
TgetDeclaredAnnotation(Class<T>)X
Annotation[]getDeclaredAnnotations()X
T[]getDeclaredAnnotationsByType(Class<T>)XX

For an invocation ofget[Declared]AnnotationsByType(Class <T>), the order of annotations which are directly or indirectly present on an elementE is computed as if indirectly present annotations onE are directly present onE 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 typeT is originallynot repeatable and later modified to be repeatable. The containing annotation type forT isTC.

  • ModifyingT to be repeatable is source and binary compatible with existing uses ofT and with existing uses ofTC. That is, for source compatibility, source code with annotations of typeT or of typeTC will still compile. For binary compatibility, class files with annotations of typeT or of typeTC (or with other kinds of uses of typeT or of typeTC) will link against the modified version ofT if they linked against the earlier version. (An annotation typeTC may informally serve as an acting containing annotation type beforeT is modified to be formally repeatable. Alternatively, whenT is made repeatable,TC can be introduced as a new type.)
  • If an annotation typeTC is present on an element, andT is modified to be repeatable withTC as its containing annotation type then:
    • The change toT is behaviorally compatible with respect to theget[Declared]Annotation(Class<T>) (called with an argument ofT orTC) and get[Declared]Annotations() methods because the results of the methods will not change due toTC becoming the containing annotation type forT.
    • The change toT changes the results of the get[Declared]AnnotationsByType(Class<T>) methods called with an argument ofT, because those methods will now recognize an annotation of typeTC as a container annotation forT and will "look through" it to expose annotations of typeT.
  • If an annotation of typeT is present on an element andT is made repeatable and more annotations of typeT are added to the element:
    • The addition of the annotations of typeT is both source compatible and binary compatible.
    • The addition of the annotations of typeT changes the results of theget[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 typeT.
    • The addition of the annotations of typeT changes the results of theget[Declared]AnnotationsByType(Class<T>) methods, because their results will expose the additional annotations of typeT whereas previously they exposed only a single annotation of typeT.

If an annotation returned by a method in this interface contains (directly or indirectly) aClass-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 aTypeNotPresentException.

Similarly, attempting to read an enum-valued member will result in aEnumConstantNotPresentException if the enum constant in the annotation is no longer present in the enum class.

If an annotation typeT is (meta-)annotated with an@Repeatable annotation whose value element indicates a typeTC, butTC does not declare avalue() method with a return type ofT[], then an exception of typeAnnotationFormatError is thrown.

Finally, attempting to read a member whose definition has evolved incompatibly will result in aAnnotationTypeMismatchException or anIncompleteAnnotationException.

Since:
1.5
See Also:

  • Method Details

    • isAnnotationPresent

      default boolean isAnnotationPresent(Class<? extendsAnnotation> annotationClass)
      Returns true if an annotation for the specified type ispresent 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

      Implementation Requirements:
      The default implementation returns getAnnotation(annotationClass) != null.
      Parameters:
      annotationClass - the Class object corresponding to the annotation type
      Returns:
      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
      Since:
      1.5

    • getAnnotation

      <T extendsAnnotation> T getAnnotation(Class<T> annotationClass)
      Returns this element's annotation for the specified type if such an annotation ispresent, else null.
      Type Parameters:
      T - the type of the annotation to query for and return if present
      Parameters:
      annotationClass - the Class object corresponding to the annotation type
      Returns:
      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
      Since:
      1.5

    • getAnnotations

      Annotation[] getAnnotations()
      Returns annotations that arepresent on this element. If there are no annotationspresent 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:
      annotations present on this element
      Since:
      1.5

    • getAnnotationsByType

      default <T extendsAnnotation> T[] getAnnotationsByType(Class<T> annotationClass)
      Returns annotations that areassociated with this element. If there are no annotationsassociated with this element, the return value is an array of length 0. The difference between this method andgetAnnotation(Class) is that this method detects if its argument is arepeatable annotation type (JLS9.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.
      Implementation Requirements:
      The default implementation first callsgetDeclaredAnnotationsByType(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 thisAnnotatedElement is a class and the argument type is an inheritable annotation type, and the superclass of thisAnnotatedElement is non-null, then the returned result is the result of callinggetAnnotationsByType(Class) on the superclass with annotationClass as the argument. Otherwise, a zero-length array is returned.
      Type Parameters:
      T - the type of the annotation to query for and return if present
      Parameters:
      annotationClass - the Class object corresponding to the annotation type
      Returns:
      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
      Since:
      1.8

    • getDeclaredAnnotation

      default <T extendsAnnotation> T getDeclaredAnnotation(Class<T> annotationClass)
      Returns this element's annotation for the specified type if such an annotation isdirectly present, else null. This method ignores inherited annotations. (Returns null if no annotations are directly present on this element.)
      Implementation Requirements:
      The default implementation first performs a null check and then loops over the results ofgetDeclaredAnnotations() returning the first annotation whose annotation type matches the argument type.
      Type Parameters:
      T - the type of the annotation to query for and return if directly present
      Parameters:
      annotationClass - the Class object corresponding to the annotation type
      Returns:
      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
      Since:
      1.8

    • getDeclaredAnnotationsByType

      default <T extendsAnnotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass)
      Returns this element's annotation(s) for the specified type if such annotations are eitherdirectly present orindirectly 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 andgetDeclaredAnnotation(Class) is that this method detects if its argument is arepeatable annotation type (JLS9.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.
      Implementation Requirements:
      The default implementation may callgetDeclaredAnnotation(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 typeannotationClass are found to be both directly and indirectly present, thengetDeclaredAnnotations() will get called to determine the order of the elements in the returned array.

      Alternatively, the default implementation may callgetDeclaredAnnotations() a single time and the returned array examined for both directly and indirectly present annotations. The results of callinggetDeclaredAnnotations() are assumed to be consistent with the results of callinggetDeclaredAnnotation(Class).

      Type Parameters:
      T - the type of the annotation to query for and return if directly or indirectly present
      Parameters:
      annotationClass - the Class object corresponding to the annotation type
      Returns:
      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
      Since:
      1.8

    • getDeclaredAnnotations

      Annotation[] getDeclaredAnnotations()
      Returns annotations that aredirectly present on this element. This method ignores inherited annotations. If there are no annotationsdirectly 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:
      annotations directly present on this element
      Since:
      1.5