注解基本概要:
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface FieldMap {
- 注解三要素:标识符
@interface
+ 两个必填项@Target
和@Retention
@Target
表示注解加在哪个范围
a. 类或接口TYPE
b. 属性FIELD
c. 方法METHOD
d. 构造方法CONSTRUCTOR
e. 方法参数PARAMETER@Retention
表示保持在哪个周期,其中大部分是在运行期。不标注@Retention
默认在仅CLASS
。
a. 编译期SOURCE如@Override和@SuppressWarnings
b. 仅CLASS
c. 运行期RUNTIME@Documented
:Javadoc工具会将此注解标记元素的注解信息包含在javadoc中。注解信息默认不会包含在Javadoc中,可以详见另一篇博文「@Documented 的作用」 我基本是推荐加上的。@Target
、@Retention
、@Repeatable
(重复注解)和@Inherited
(注解继承),被称为元注解
(meta annotation),可以修饰其他注解。- 注解类的属性中,value属性为通用属性,可以直接常量在括号里,省略
value =""
。 - 配置参数必须是常量,包括所有 基本类型、String、Class以及枚举(包括对应的数组)。
# javadoc 工具示例
javadoc -d /目录 org.xxx.包名 -encoding utf-8 -charset utf-8
什么是重复注解
允许在同一声明类型(类,属性,或方法)上多次使用同一个注解。这个注解在 jdk 1.8 中加入。
例如(自定义注解):
@FieldMap(channel = "classroom1", value = "name")
@FieldMap(channel = "classroom2", value = "peopleName")
private String studentName;
这样可以在获取 两条注解 后,根据channel去判断该取哪个值;
步骤
- 先建立一个普通注解类
FieldMap.class
。
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FieldMap {
String channel() default "";
String value(); // 如果不写default默认值,则该选项为必填项
}
- 加入一行
@Repeatable(FieldMaps.class)
。
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(FieldMaps.class)
@Documented
public @interface FieldMap {
String channel();
String value();
}
- 新建对应包裹类
FieldMaps
,@Target
和@Retention
要和被包裹的注解相同。同时,属性为被包裹的注解数组FieldMap[]
。因为只含有一个数组属性,所以属性值就选默认的value(),并且不加默认值。
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FieldMaps {
FieldMap[] value();
}
使用
getAnnotation()
和getAnnotationsByType()
,一个获取单个注解,一个获取相同类型的注解数组。- 在判断属性是否含有该注解时,虽然用的是
@FieldMap
注解,但其实编译后是被@FieldMaps
包裹。
- 普通的注解使用:
if (field.isAnnotationPresent(FieldMap.class)) {
FieldMap annotation = field.getAnnotation(FieldMap.class);
String value = annotation.value();
}
- 重复注解使用:
if (field.isAnnotationPresent(FieldMaps.class)) { // 此处取得是 FieldMaps
FieldMap[] annotationsByType = field.getAnnotationsByType(FieldMap.class); // 此处用的是 getAnnotationsByType() 方法,返回的数组
for (FieldMap annotation : annotationsByType) {
if ("classroom1".equals(annotation.channel())) { // 通过annotation.channel() 获取到第一个进行判断
String value = annotation.value();
break; // 为了防止有属性值相同的情况,直接中止循环
}
}
}
总结
- 注解在 jdk 1.5 加入,其实原本有重复注解,需要用包装类当容器来存多个注解。所以 jdk 1.8 引入的
重复注解:@Repeatable
,其实是语法糖。
/**
* jdk 1.5
*/
@FieldMaps({@FieldMap("name"), @FieldMap("peopleName")})
private String studentName;
/**
* jdk 1.8
*/
@FieldMap("name")
@FieldMap("peopleName")
private String studentName;
-
注释类FieldMap
被@Repeatable(FieldMaps.class)
注释着,而 FieldMaps 其实是一个容器,它持有 FieldMap, 只不过编译器选择了隐藏它的存在。所以 studentName 属性就可以被 FieldMap 注释两次。 -
反射 API 提供一个新方法:
getAnnotationsByType()
来返回重复注释的类型。 -
Filterable.class.getAnnotation(FieldMaps.class)
会返回编译器注入的 FieldMaps 实例。