Module java.base
Package java.lang.reflect

Interface AnnotatedElement

所有已知的子接口:
AnnotatedArrayType, AnnotatedParameterizedType, AnnotatedType, AnnotatedTypeVariable, AnnotatedWildcardType, GenericDeclaration, TypeVariable<D>
所有已知的实现类:
AccessibleObject, Class, Constructor, Executable, Field, Method, Module, Package, Parameter, RecordComponent
public interface AnnotatedElement
代表当前在此VM中运行的程序的注解构造。构造可以是元素或类型。元素上的注解位于声明上，而类型上的注解位于类型名称的特定使用上。根据Java语言规范第9.7.4节，元素上的注解是声明注解，类型上的注解是类型注解。请注意，AnnotatedType接口及其子接口上的方法返回的任何注解都是类型注解，因为可能被注解的实体是一个类型。在AnnotatedType层次结构之外的方法返回的注解是声明注解。

此接口允许通过反射读取注解。此接口中的所有方法返回的注解都是不可变的且可序列化的。此接口的方法返回的数组可能会被调用者修改，而不会影响返回给其他调用者的数组。

getAnnotationsByType(Class)和getDeclaredAnnotationsByType(Class)方法支持在元素上具有相同类型的多个注解。如果任一方法的参数是可重复注解类型（JLS第9.6节），则该方法将“查找”容器注解（JLS第9.7节），如果存在，则返回容器内的任何注解。容器注解可以在编译时生成，用于包装参数类型的多个注解。

在整个此接口中使用术语直接存在、间接存在、存在和关联来精确描述方法返回的注解：

  • 如果元素E具有RuntimeVisibleAnnotations或RuntimeVisibleParameterAnnotations或RuntimeVisibleTypeAnnotations属性，并且该属性包含注解A，则注解A在元素E上是直接存在。
  • 如果元素E具有RuntimeVisibleAnnotations或RuntimeVisibleParameterAnnotations或RuntimeVisibleTypeAnnotations属性，并且A的类型是可重复的，并且该属性包含确切包含A的值元素和其类型为A的类型的容器注解中的一个注解，则注解A在元素E上是间接存在。
  • 如果在元素E上：
    • 注解A直接存在；或
    • 没有A类型的注解直接存在于E上，并且E是一个类，并且A的类型是可继承的，并且A存在于E的超类上。
  • 如果在元素E上：
    • 注解A直接或间接存在；或
    • 没有A类型的注解直接或间接存在于E上，并且E是一个类，并且A的类型是可继承的，并且A与E的超类关联。

下表总结了此接口中不同方法检查的注解存在类型。

不同AnnotatedElement方法检测到的存在类型概述
方法 存在类型
返回类型 签名 直接存在 间接存在 存在 关联
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

对于对get[Declared]AnnotationsByType(Class <T>)的调用，直接或间接存在于元素E上的注解的顺序被计算为间接存在于E上的注解在其容器注解的值元素中出现的顺序中直接存在于E上的注解。

如果注解类型T最初不可重复，并且后来修改为可重复，则需要牢记几个兼容性问题。对于T的包含注解类型为TC。

  • 将T修改为可重复与现有对T和对TC的使用的源代码和二进制兼容。也就是说，对于源代码兼容性，具有类型T或类型TC的注解的源代码仍将编译。对于二进制兼容性，具有类型T或类型TC的类文件（或具有类型T或类型TC的其他类型的使用）将链接到修改后的T版本，如果它们链接到先前的版本。（在T被正式修改为可重复之前，注解类型TC可以非正式地充当包含注解类型。或者，当T被使为可重复时，TC可以作为新类型引入。）
  • 如果注解类型TC存在于元素上，并且T被修改为可重复，其中TC作为其包含注解类型，则：
    • 对于get[Declared]Annotation(Class<T>)（使用T或TC的参数调用）和get[Declared]Annotations()方法，对T的更改在行为上与get[Declared]AnnotationsByType(Class<T>)方法的结果兼容，因为这些方法的结果不会因TC成为T的包含注解类型而改变。
    • 对于get[Declared]AnnotationsByType(Class<T>)方法（使用T作为参数调用），对T的更改会改变结果，因为这些方法现在将会将TC类型的注解识别为T的容器注解，并将“查找”它以公开T类型的注解。
  • 如果元素上存在类型为T的注解，并且T被设置为可重复，并且向元素添加了更多类型为T的注解：
    • 添加类型为T的注解既是源代码兼容又是二进制兼容的。
    • 添加类型为T的注解会改变get[Declared]Annotation(Class<T>)方法和get[Declared]Annotations()方法的结果，因为这些方法现在只会在元素上看到一个容器注解，而不会看到类型为T的注解。
    • 添加类型为T的注解会改变get[Declared]AnnotationsByType(Class<T>)方法的结果，因为它们的结果现在将公开更多类型为T的注解，而以前它们只公开一个类型为T的注解。

如果此接口中的方法返回的注解包含（直接或间接）引用此VM中不可访问的类的Class值成员，则尝试通过调用返回的注解上的相关Class返回方法读取该类将导致TypeNotPresentException。

类似地，尝试读取枚举值成员将导致EnumConstantNotPresentException，如果注解中的枚举常量不再存在于枚举类中。

如果注解类型T（元）注解为一个@Repeatable注解，其值元素指示一个类型TC，但TC未声明具有返回类型为T[]的value()方法，则将抛出一个类型为AnnotationFormatError的异常。

最后，尝试读取定义已发生不兼容演变的成员将导致AnnotationTypeMismatchException或IncompleteAnnotationException。

自从:
1.5
参见:

  • Method Details

    • isAnnotationPresent

      default boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)
      如果指定类型的注解在此元素上存在，则返回true，否则返回false。此方法主要设计用于方便访问标记注解。

      此方法返回的真值等同于：getAnnotation(annotationClass) != null

      实现要求：
      默认实现返回 getAnnotation(annotationClass) != null。
      参数：
      annotationClass - 对应于注解类型的Class对象
      返回：
      如果此元素上存在指定的注解类型的注解，则返回true，否则返回false
      抛出：
      NullPointerException - 如果给定的注解类为null
      自Java版本：
      1.5

    • getAnnotation

      <T extends Annotation> T getAnnotation(Class<T> annotationClass)
      返回此元素的指定类型的注解，如果存在则返回该注解，否则返回null。
      类型参数：
      T - 要查询并返回的注解类型
      参数：
      annotationClass - 对应于注解类型的Class对象
      返回：
      如果此元素上存在指定的注解类型的注解，则返回该注解，否则返回null
      抛出：
      NullPointerException - 如果给定的注解类为null
      自Java版本：
      1.5

    • getAnnotations

      Annotation[] getAnnotations()
      返回此元素上存在的注解。如果此元素上不存在注解，则返回长度为0的数组。调用此方法的调用者可以修改返回的数组；这不会影响返回给其他调用者的数组。
      返回：
      此元素上存在的注解
      自Java版本：
      1.5

    • getAnnotationsByType

      default <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass)
      返回与此元素关联的注解。如果此元素上没有与之关联的注解，则返回长度为0的数组。此方法与getAnnotation(Class)方法的区别在于，此方法会检测其参数是否为可重复注解类型（JLS 9.6），如果是，则尝试通过“查找”容器注解来找到一个或多个该类型的注解。调用此方法的调用者可以修改返回的数组；这不会影响返回给其他调用者的数组。
      实现要求：
      默认实现首先调用getDeclaredAnnotationsByType(Class)，将annotationClass作为参数传递。如果返回的数组长度大于零，则返回该数组。如果返回的数组长度为零，并且此AnnotatedElement是类且参数类型为可继承注解类型，并且此AnnotatedElement的超类不为null，则通过在超类上调用getAnnotationsByType(Class)，参数为annotationClass，来确定返回结果。否则，返回一个长度为零的数组。
      类型参数：
      T - 要查询并返回的注解类型
      参数：
      annotationClass - 对应于注解类型的Class对象
      返回：
      如果与此元素关联的注解类型的所有注解存在，则返回所有此元素的注解，否则返回长度为零的数组
      抛出：
      NullPointerException - 如果给定的注解类为null
      自Java版本：
      1.8

    • getDeclaredAnnotation

      default <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass)
      返回此元素的指定类型的注解，如果直接存在则返回该注解，否则返回null。此方法忽略继承的注解。（如果此元素上没有直接存在的注解，则返回null。）
      实现要求：
      默认实现首先执行空值检查，然后循环遍历getDeclaredAnnotations()的结果，返回第一个注解类型与参数类型匹配的注解。
      类型参数：
      T - 要查询并返回的注解类型
      参数：
      annotationClass - 对应于注解类型的Class对象
      返回：
      如果直接存在于此元素上的指定注解类型的注解，则返回该注解，否则返回null
      抛出：
      NullPointerException - 如果给定的注解类为null
      自Java版本：
      1.8

    • getDeclaredAnnotationsByType

      default <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass)
      返回此元素的指定类型的注解（如果直接存在或间接存在）。此方法忽略继承的注解。如果此元素上不存在指定的注解直接或间接存在，则返回长度为0的数组。此方法与getDeclaredAnnotation(Class)方法的区别在于，此方法会检测其参数是否为可重复注解类型（JLS 9.6），如果是，则尝试通过“查找”容器注解（如果存在）来找到一个或多个该类型的注解。调用此方法的调用者可以修改返回的数组；这不会影响返回给其他调用者的数组。
      实现要求：
      默认实现可能会多次调用getDeclaredAnnotation(Class)，以查找直接存在的注解，并且如果注解类型是可重复的，则查找容器注解。如果发现注解类型annotationClass的注解既直接存在又间接存在，则将调用getDeclaredAnnotations()来确定返回数组中元素的顺序。

      另外，默认实现也可能只调用一次getDeclaredAnnotations()，并检查返回的数组中直接存在和间接存在的注解。假定调用getDeclaredAnnotations()的结果与调用getDeclaredAnnotation(Class)的结果一致。

      类型参数：
      T - 要查询并返回的注解类型
      参数：
      annotationClass - 对应于注解类型的Class对象
      返回：
      如果直接或间接存在于此元素上的指定注解类型的所有注解，则返回所有此元素的注解，否则返回长度为0的数组
      抛出：
      NullPointerException - 如果给定的注解类为null
      自Java版本：
      1.8

    • getDeclaredAnnotations

      Annotation[] getDeclaredAnnotations()
      返回此元素上直接存在的注解。此方法忽略继承的注解。如果此元素上没有直接存在的注解，则返回长度为0的数组。调用此方法的调用者可以修改返回的数组；这不会影响返回给其他调用者的数组。
      返回：
      直接存在于此元素上的注解
      自Java版本：
      1.5