AnnotatedElement (Java Platform SE 8 )

All Known Subinterfaces:

AnnotatedArrayType ， AnnotatedParameterizedType ， AnnotatedType ， AnnotatedTypeVariable ， AnnotatedWildcardType ， GenericDeclaration ， TypeVariable <D>

所有已知实现类：

AccessibleObject ，类， Constructor ， Executable ， Field ，方法，软件包， 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 >)的get[Declared]AnnotationsByType( Class < T >) ，直接或间接地出现在元素E上的get[Declared]AnnotationsByType( Class < T >)的顺序被计算，就好像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的变化而变化的结果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型注释。
如果此接口中的方法返回的注释包含（直接或间接）引用此虚拟机中无法访问的类的类值的成员，则尝试通过在返回的注释上调用相关的类返回方法来读取类将导致TypeNotPresentException 。

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

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

最后，尝试读取其定义不兼容的成员将导致AnnotationTypeMismatchException或IncompleteAnnotationException 。
从以下版本开始：

1.5

另请参见：

EnumConstantNotPresentException ， TypeNotPresentException ， AnnotationFormatError ， AnnotationTypeMismatchException ， IncompleteAnnotationException

方法摘要

所有方法接口方法抽象方法 Default Methods
Modifier and Type	Method and Description
`<T extends Annotation> T`	`getAnnotation(类<T> annotationClass)` 返回该元素的，如果这样的注释，否则返回null指定类型的注释。
`Annotation[]`	`getAnnotations()` 返回此元素上存在的注释。
`default <T extends Annotation> T[]`	`getAnnotationsByType(类<T> annotationClass)` 返回与此元素相关联的注释。
`default <T extends Annotation> T`	`getDeclaredAnnotation(类<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 - 如果给定的注释类为空
    
    从以下版本开始：
    
    1.5
  - getAnnotation
```
<T extends Annotation> T getAnnotation(类<T> annotationClass)
```
    返回该元素的，如果这样的注释，否则返回null指定类型的注释。
    
    参数类型
    
    T - 要查询的注释的类型，如果存在则返回
    
    参数
    
    annotationClass - 对应于注释类型的Class对象
    
    结果
    
    该元素的注释指定的注释类型，如果存在于此元素，否则为null
    
    异常
    
    NullPointerException - 如果给定的注释类为空
    
    从以下版本开始：
    
    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的AnnotatedElement是非空的，则返回的结果是在超类上调用getAnnotationsByType(Class)的结果，具有annotationClass作为论证。否则返回零长度的数组。
    
    参数类型
    
    T - 要查询的注释的类型，如果存在则返回
    
    参数
    
    annotationClass - 对应于注释类型的Class对象
    
    结果
    
    如果与此元素相关联，则指定注释类型的所有元素注释，否则为长度为零的数组
    
    异常
    
    NullPointerException - 如果给定的注释类为空
    
    从以下版本开始：
    
    1.8
  - getDeclaredAnnotation
```
default <T extends Annotation> T getDeclaredAnnotation(类<T> annotationClass)
```
    如果这样的注释直接存在 ，则返回指定类型的元素注释，否则返回null。此方法忽略继承的注释。（如果此元素上没有注释，则返回null）
    
    实现要求：
    
    默认的实现首先进行零检查，然后遍历结果 getDeclaredAnnotations()返回第一个注释，其注释类型的参数类型相匹配。
    
    参数类型
    
    T - 查询的注释类型，如果直接出现则返回
    
    参数
    
    annotationClass - 对应于注释类型的Class对象
    
    结果
    
    如果直接出现在该元素上，则指定注释类型的元素注释，否则为null
    
    异常
    
    NullPointerException - 如果给定的注释类为空
    
    从以下版本开始：
    
    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

Interface AnnotatedElement

方法摘要

方法详细信息

isAnnotationPresent

getAnnotation

getAnnotations

getAnnotationsByType

getDeclaredAnnotation

getDeclaredAnnotationsByType

getDeclaredAnnotations