Module  java.base
软件包  java.lang.reflect

Interface AnnotatedElement

  • All Known Subinterfaces:
    AnnotatedArrayType ， AnnotatedParameterizedType ， AnnotatedType ， AnnotatedTypeVariable ， AnnotatedWildcardType ， GenericDeclaration ， TypeVariable<D>
    所有已知实现类：
    AccessibleObject ， Class ， Constructor ， Executable ， Field ， 方法 ， Module ， 软件包 ， Parameter 

    public interface AnnotatedElement
    表示当前在此VM中运行的程序的注释元素。 该界面允许反射读取注释。 该界面中由方法返回的所有注释都是不可变的和可序列化的。 由该接口的方法返回的数组可以由调用者修改，而不会影响返回给其他调用者的数组。

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

    直接呈现 ， 间接存在 ， 呈现和关联的术语在整个界面中被使用以精确描述通过方法返回哪些注释：

    • 如果E具有RuntimeVisibleAnnotations或RuntimeVisibleParameterAnnotations或RuntimeVisibleTypeAnnotations属性，则注释A 直接显示在元素E上 ，并且属性包含A。
    • 如果E具有RuntimeVisibleAnnotations或RuntimeVisibleParameterAnnotations或RuntimeVisibleTypeAnnotations属性，并且A的类型是可重复的，则注释A 间接存在于元素E上 ，并且该属性仅包含一个注释，其值元素包含A ，其类型是包含注释类型A的类型。
    • 注释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 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

    对于调用get[Declared]AnnotationsByType( Class < T >) ，直接或间接出现在元素E上的注释的顺序被计算，就好像在E上间接存在的注释直接出现在E上， get[Declared]AnnotationsByType( Class < T >)是以它们的容器注释的顺序，以它们出现在容器注释的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()方法的行为兼容，因为由于TC成为T的包含注释类型， get[Declared]Annotations()方法的结果不会改变。
      • 至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型注释。

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

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

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

    最后，试图读取其定义不一致的成员将导致一个AnnotationTypeMismatchException或一个IncompleteAnnotationException 。

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

    • 方法详细信息

      • isAnnotationPresent

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

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

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

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

      • getAnnotation

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

      • getAnnotations

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

      • getAnnotationsByType

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

      • getDeclaredAnnotation

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

      • getDeclaredAnnotations

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