模块 java.base
包 java.lang.reflect

接口 AnnotatedElement

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

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

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

术语 directly present 、 indirectly present 、 present 和 associated 在整个接口中用于精确描述方法返回哪些注释：

  • 一个注解A在一个元素上是directly presentE如果E具有 RuntimeVisibleAnnotations 或 RuntimeVisibleParameterAnnotations 或 RuntimeVisibleTypeAnnotations 属性，并且该属性包含A.
  • 一个注解A是 indirectly present 在一个元素上E如果E具有 RuntimeVisibleAnnotations 或 RuntimeVisibleParameterAnnotations 或 RuntimeVisibleTypeAnnotations 属性，并且A的类型是可重复的，属性只包含一个注解，其值元素包含A并且其类型是包含的注解类型A的类型。
  • 一个注解A在一个元素上是presentE如果：
    • A直接出现在E;或者
    • 没有注解A的类型直接出现在E， 和E是一个类，并且A的类型是可继承的，并且A存在于超类中E.
  • 一个注解A是 associated 有一个元素E如果：
    • A直接或间接存在于E;或者
    • 没有注解A的类型直接或间接存在于E， 和E是一个类，并且A的类型是可继承的，并且A与超类关联E.

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

不同 AnnotatedElement 方法检测到的存在类型概述
Method 存在的种类
返回类型 Signature 直接存在 间接存在 展示 联系
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最初是 not 可重复的，后来修改为可重复的。包含的注解类型为T是TC.

  • 修改T可重复是与现有用途的源和二进制兼容T和现有的用途TC.也就是说，为了源代码兼容性，源代码带有类型的注解T或类型TC仍然会编译。为了二进制兼容性，带有类型注解的类文件T或类型TC（或与类型的其他用途T或类型TC) 将链接到修改后的版本T如果他们链接到早期版本。 （注解类型TC之前可以非正式地充当包含注解类型的行为T被修改为正式可重复的。或者，当T是可重复的，TC可以作为新类型引入。）
  • 如果注解类型TC存在于一个元素上，并且T被修改为可重复的TC作为其包含的注解类型，则：
    • 更改为T在行为上与 get[Declared]Annotation(Class<T>) 兼容（使用参数调用T或者TC和 get[Declared]Annotations() 方法，因为这些方法的结果不会因以下原因而改变TC成为包含注解类型T.
    • 更改为T更改使用参数调用的 get[Declared]AnnotationsByType(Class<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.

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

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

如果注解类型T使用 @Repeatable 注释进行（元）注释，其值元素指示类型TC， 但TC没有声明返回类型为 value() 的方法T[] ，则抛出 AnnotationFormatError 类型的异常。

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

自从：
1.5
参见：

  • 方法详情

    • isAnnotationPresent

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

      该方法返回的真值相当于：getAnnotation(annotationClass) != null

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

    • getAnnotation

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

    • getAnnotations

      Annotation [] getAnnotations()
      返回此元素上的 present 注释。如果该元素上没有注解present，则返回值为长度为0的数组。该方法的调用者可以自由修改返回的数组；它不会影响返回给其他调用者的数组。
      返回：
      此元素上的注释
      自从：
      1.5

    • getAnnotationsByType

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

    • getDeclaredAnnotation

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

    • getDeclaredAnnotationsByType

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

      或者，默认实现可以调用 getDeclaredAnnotations() 一次，并检查返回的数组是否有直接和间接存在的注释。假定调用getDeclaredAnnotations() 的结果与调用getDeclaredAnnotation(Class) 的结果一致。

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

    • getDeclaredAnnotations

      Annotation [] getDeclaredAnnotations()
      返回此元素上的 directly present 注释。此方法忽略继承的注释。如果该元素上没有注解directly present，则返回值为长度为0的数组。该方法的调用者可以自由修改返回的数组；它不会影响返回给其他调用者的数组。
      返回：
      注释直接出现在这个元素上
      自从：
      1.5