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

Interface AnnotatedElement

  • All Known Subinterfaces:
    AnnotatedArrayTypeAnnotatedParameterizedTypeAnnotatedTypeAnnotatedTypeVariableAnnotatedWildcardTypeGenericDeclarationTypeVariable<D>
    所有已知实现类:
    AccessibleObject构造器Executable字段方法模块软件包Parameter

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

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

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

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

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

    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的注释的源代码仍将编译。 对于二进制兼容性,注释类型为TTC类型(或使用T类型或TC类型的其他类型)的类文件将链接到T的修改版本(如果它们与早期版本链接)。 (注释类型TC可以在T被修改为正式可重复之前非正式地用作包含注释类型的动作。或者,当T可重复时, TC可以作为新类型引入。)
    • 如果元素上存在注释类型TC ,并且T被修改为可重复, TC作为其包含注释类型,则:
      • T的改变在行为上与get[Declared]Annotation(Class<T>) (使用TTC的参数调用)和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的异常。

    最后,尝试读取其定义已演变为不兼容的成员将导致AnnotationTypeMismatchExceptionIncompleteAnnotationException

    从以下版本开始:
    1.5
    另请参见:
    EnumConstantNotPresentExceptionTypeNotPresentExceptionAnnotationFormatErrorAnnotationTypeMismatchExceptionIncompleteAnnotationException
    • 方法详细信息

      • 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