-
- 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 AssociatedT
getAnnotation(Class<T>)
XAnnotation[]
getAnnotations()
XT[]
getAnnotationsByType(Class<T>)
XT
getDeclaredAnnotation(Class<T>)
XAnnotation[]
getDeclaredAnnotations()
XT[]
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的注释既是源兼容的又是二进制兼容的。
- 添加类型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
。
-
-
方法摘要
所有方法 实例方法 抽象方法 Default Methods 变量和类型 方法 描述 <T extends Annotation>
TgetAnnotation(类<T> annotationClass)
返回该元素的,如果这样的注释 ,否则返回null指定类型的注释。Annotation[]
getAnnotations()
返回此元素上 存在的注释。default <T extends Annotation>
T[]getAnnotationsByType(类<T> annotationClass)
返回与此元素 关联的注释。default <T extends Annotation>
TgetDeclaredAnnotation(类<T> annotationClass)
如果 直接存在这样的注释,则返回指定类型的此元素的注释,否则返回null。Annotation[]
getDeclaredAnnotations()
返回 直接出现在此元素上的注释。default <T extends Annotation>
T[]getDeclaredAnnotationsByType(类<T> annotationClass)
如果此类注释 直接存在或 间接存在 ,则返回指定类型的此元素的注释。default boolean
isAnnotationPresent(类<? extends Annotation> annotationClass)
如果此元素上 存在指定类型的注释,则返回true,否则返回false。
-
-
-
方法详细信息
-
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
-
-