一、概述
Annotation 是Java JDK 5.0 映入的新特性,是一种安全的注解机制,用来标注数据元素与程序元素(类、方法、属性等)之间的关系。注解不影响程序的运行,只是一种标记的方式而已,获得注解的相关信息,可以通过反射形式获取。
二、基本API摘要
Annotation 相关的API类在java.lang.annotaiton 包下,包含以下
(1). 注解类型(Annotation Types) API
注解类型 | 含义 |
---|---|
Documented | 表示含有该注解类型的元素(带有注释的)会通过javadoc或类似工具进行文档化 |
Inherited | 表示注解类型能被自动继承 |
Retention | 表示注解类型的存活时长 |
Target | 表示注解类型所适用的程序元素的种类 |
(2). 枚举(Enum) API
枚举 | 含义 |
---|---|
ElementType | 程序元素类型,用于Target注解类型 |
RetentionPolicy | 注解保留策略,用于Retention注解类型 |
(3). 异常和错误 API
异常/错误 | 含义 |
---|---|
AnnotationTypeMismatchException | 当注解经过编译(或序列化)后,注解类型改变的情况下,程序视图访问该注解所对应的元素,则抛出此异常 |
IncompleteAnnotationException | 当注解经过编译(或序列化)后,将其添加到注解类型定义的情况下,程序视图访问该注解所对应的元素,则抛出此异常。 |
AnnotationFormatError | 当注解解析器试图从类文件中读取注解并确定注解出现异常时,抛出该错误 |
三、注解类型
注解类型用于在自定义注解时修饰相关策略于机制,包好Document、Inherited、Retention和Target。
(1). Document
源码:
@Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.ANNOTATION_TYPE) public @interface Documented { }
指示某一类型的注释将通过 javadoc 和类似的默认工具进行文档化。应使用此类型来注释这些类型的声明:其注释会影响由其客户端注释的元素的使用。如果类型声明是用 Documented 来注释的,则其注释将成为注释元素的公共 API 的一部分。
(2).Inherited
源码:
@Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.ANNOTATION_TYPE) public @interface Inherited { }
指示注释类型被自动继承。如果在注释类型声明中存在 Inherited 元注释,并且用户在某一类声明中查询该注释类型,同时该类声明中没有此类型的注释,则将在该类的超类中自动查询该注释类型。此过程会重复进行,直
到找到此类型的注释或到达了该类层次结构的顶层 (Object) 为止。如果没有超类具有该类型的注释,则查询将指示当前类没有这
样的注释。
注意,如果使用注释类型注释类以外的任何事物,此元注释类型都是无效的。还要注意,此元注释仅促成从超类继承注释;对已实现接口的注释无效。
(3).Rntention
源码:
@Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.ANNOTATION_TYPE) public @interface Retention { /** * Returns the retention policy. * @return the retention policy */ RetentionPolicy value(); }
指示注释类型的注释要保留多久。如果注释类型声明中不存在 Retention 注释,则保留策略默认为
RetentionPolicy.CLASS
。
只有元注释类型直接用于注释时,Target 元注释才有效。如果元注释类型用作另一种注释类型的成员,则无效。
Retention 保留机制由RetentionPolicy 枚举提供,包含如下选项
RetentionPolicy | 含义 |
SOURCE | 源码中保留,编译器在编译时丢弃 |
CLASS | 保留在Class 字节码文件中,但是在运行时JVN 不保留此注解 |
RUNTIME | 保留在Class 字节码文件中,但是在运行时JVN 保留此注解,因此可以使用反射获取 |
(4).Target
源码:
@Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.ANNOTATION_TYPE) public @interface Target { /** * Returns an array of the kinds of elements an annotation type * can be applied to. * @return an array of the kinds of elements an annotation type * can be applied to */ ElementType[] value(); }指示注释类型所适用的程序元素的种类。如果注释类型声明中不存在 Target 元注释,则声明的类型可以用在任一程序元素上。如果存在这样的元注释,则编译器强制实施指定的使用限制。修饰的程序元素有ElementType 枚举修饰,包含以下类型:
ElementType | 含义 |
---|---|
ANNOTATION_TYPE | 注解类型声明 |
CONSTRUCTOR | 构造方法声明 |
FIELD | 字段声明(包括枚举常量) |
LOCAL_VARIABLE | 局部变量声明 |
METHOD | 方法声明 |
PACKAGE | 包声明 |
PARAMETER | 参数声明 |
TYPE | 类、接口(包括注解类型)或枚举声明 |
四、获取注解
获取注解的内容可以通过Class 中的相关方法获取,涉及到一下方法
返回值 | 方法 | 解释 |
---|---|---|
T | getAnnotation(Class annotationClass) | 当存在该元素的指定类型注解,则返回相应注释,否则返回null |
Annotation[] | getAnnotations() | 返回此元素上存在的所有注解 |
Annotation[] | getDeclaredAnnotations() | 返回直接存在于此元素上的所有注解。 |
boolean | isAnnotationPresent(Class<? extends Annotation> annotationClass) | 当存在该元素的指定类型注解,则返回true,否则返回false |
语法:
public @interface Annotiaon_Name {
[FiledType filedName() [defualt ] ];
}
注意
1、参数类型只支持基本数据类型、String 、枚举、数组和Annotation
2、可以使用default 指定默认值
实例:
a>.定义自定义注解
@Document
@Inherited
@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Test {
public String name default "张三";
public int age;
}
b>.使用注解
public class User {
@Test(name="李四", age = 20)
public String A;
}
c>.使用反射获得注解相关的信息
Test test = Test.class.
getAnnotation(Test.class);
System.out.println(“name : ” + test.name + " age: " + test.age );