模块  java.base
软件包  java.lang.reflect

Interface AnnotatedElement

  • All Known Subinterfaces:
    AnnotatedArrayType ， AnnotatedParameterizedType ， AnnotatedType ， AnnotatedTypeVariable ， AnnotatedWildcardType ， GenericDeclaration ， TypeVariable<D>
    所有已知实现类：
    AccessibleObject ， 类 ， 构造器 ， Executable ， 字段 ， 方法 ， 模块 ， 软件包 ， Parameter 
    public interface AnnotatedElement
    表示当前在此VM中运行的程序的带注释的元素。 该接口允许以反射方式读取注释。 此接口中的方法返回的所有注释都是不可变的和可序列化的。 通过此接口的方法返回的数组可以由调用者修改，而不会影响返回给其他调用者的数组。

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

    在此界面中使用直接存在 ， 间接存在 ， 存在和关联的术语来精确描述方法返回的注释：

    • 如果E具有RuntimeVisibleAnnotations或RuntimeVisibleParameterAnnotations或RuntimeVisibleTypeAnnotations属性，并且该属性包含A ，则注释A 直接出现在元素E上 。
    • 如果E具有RuntimeVisibleAnnotations或RuntimeVisibleParameterAnnotations或RuntimeVisibleTypeAnnotations属性，并且A的类型是可重复的，并且该属性仅包含一个注释，其值元素包含A且其类型包含注释类型，则注释A 间接存在于元素E上一个类型。
    • 注释A出现在元素E上，如果：
      • A直接存在于E上 ; 要么
      • A的类型没有注释直接出现在E上 ， E是一个类， A的类型是可继承的， A存在于E的超类中。
    • 注释A与元素E 关联 ，如果：
      • A直接或间接存在于E ; 要么
      • A的类型没有直接或间接存在于E上 ， E是一个类， A的类型是可继承的， A与E的超类相关联。

    下表总结了此接口中不同方法检查的哪种注释存在。

    Overview of kind of presence detected by different AnnotatedElement methods 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

    为的调用get[Declared]AnnotationsByType( Class < T >) ，注释，它们可直接或间接地存在的元件E被计算为如果E上间接本注释直接存在第E代替它们的容器注释的上，在顺序的它们出现在顺序容器注释的value元素。

    如果注释类型T最初不可重复并且稍后被修改为可重复，则需要记住几个兼容性问题。 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()方法get[Declared]Annotations()因为由于TC成为T的包含注释类型，方法的结果不会改变。
      • 对T的更改会更改使用参数T调用的get[Declared]AnnotationsByType(Class<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中无法访问的类的类值成员，则尝试通过对返回的注释调用相关的类返回方法来读取该类将导致TypeNotPresentException 。

    类似地，如果注释中的枚举常量不再出现在枚举类型中，则尝试读取枚举值成员将导致EnumConstantNotPresentException 。

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

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

    从以下版本开始：
    1.5
    另请参见：
    EnumConstantNotPresentException ， TypeNotPresentException ， AnnotationFormatError ， AnnotationTypeMismatchException ， IncompleteAnnotationException

    • 方法详细信息

      • isAnnotationPresent

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

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

        默认方法的主体被指定为上面的代码。

        参数
        annotationClass - 与注释类型对应的Class对象
        结果
        如果此元素上存在指定注释类型的注释，则返回true，否则返回false
        异常
        NullPointerException - 如果给定的注释类为null
        从以下版本开始：
        1.5

      • getAnnotation

        <T extends Annotation> T getAnnotation​(类<T> annotationClass)
        返回该元素的，如果这样的注释 ，否则返回null指定类型的注释。
        参数类型
        T - 要查询的注释的类型，如果存在则返回
        参数
        annotationClass - 与注释类型对应的Class对象
        结果
        如果此元素上存在指定注释类型，则此元素的注释，否则为null
        异常
        NullPointerException - 如果给定的注释类为null
        从以下版本开始：
        1.5

      • getAnnotations

        Annotation[] getAnnotations()
        返回此元素上存在的注释。 如果没有存在于此元素上注解，返回值是长度为0这种方法的调用者可以随意修改返回的数组的数组; 它对返回给其他调用者的数组没有影响。
        结果
        此元素上的注释
        从以下版本开始：
        1.5

      • getAnnotationsByType

        default <T extends Annotation> T[] getAnnotationsByType​(类<T> annotationClass)
        返回与此元素关联的注释。 如果没有与此元素关联的注释，则返回值是长度为0的数组。此方法与getAnnotation(Class)之间的区别在于此方法检测其参数是否为可重复注释类型 （JLS 9.6），如果是，则尝试通过“查看”容器注释来查找该类型的一个或多个注释。 此方法的调用者可以自由修改返回的数组; 它对返回给其他调用者的数组没有影响。
        实现要求：
        默认的实现首先调用getDeclaredAnnotationsByType(Class)传球annotationClass作为参数。 如果返回的数组的长度大于零，则返回该数组。 如果返回的数组是零长度并且此AnnotatedElement是一个类且参数类型是可继承的注释类型，并且此AnnotatedElement的超类是非null，则返回的结果是在超类上调用getAnnotationsByType(Class)的结果，其中annotationClass作为论点。 否则，返回零长度数组。
        参数类型
        T - 要查询的注释的类型，如果存在则返回
        参数
        annotationClass - 与注释类型对应的Class对象
        结果
        如果与此元素关联，则指定注释类型的所有此元素的注释，否则为长度为零的数组
        异常
        NullPointerException - 如果给定的注释类为null
        从以下版本开始：
        1.8

      • getDeclaredAnnotation

        default <T extends Annotation> T getDeclaredAnnotation​(类<T> annotationClass)
        如果直接存在这样的注释，则返回指定类型的此元素的注释，否则返回null。 此方法忽略继承的注释。 （如果此元素上没有直接出现注释，则返回null。）
        实现要求：
        默认实现首先执行空检查，然后循环 getDeclaredAnnotations()的结果，返回其注释类型与参数类型匹配的第一个注释。
        参数类型
        T - 要查询的注释的类型，如果直接存在则返回
        参数
        annotationClass - 与注释类型对应的Class对象
        结果
        如果直接出现在此元素上，则此元素的指定注释类型的注释，否则为null
        异常
        NullPointerException - 如果给定的注释类为null
        从以下版本开始：
        1.8

      • getDeclaredAnnotationsByType

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

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

        参数类型
        T - 要查询的注释的类型，如果直接或间接存在则返回
        参数
        annotationClass - 与注释类型对应的Class对象
        结果
        如果直接或间接出现在此元素上，则指定注释类型的所有此元素的注释，否则为长度为零的数组
        异常
        NullPointerException - 如果给定的注释类为null
        从以下版本开始：
        1.8

      • getDeclaredAnnotations

        Annotation[] getDeclaredAnnotations()
        返回直接出现在此元素上的注释。 此方法忽略继承的注释。 如果此元素上没有直接存在注释，则返回值为长度为0的数组。此方法的调用者可以自由修改返回的数组; 它对返回给其他调用者的数组没有影响。
        结果
        注释直接出现在此元素上
        从以下版本开始：
        1.5