4.5、重复注解

这篇Java教程基于JDK1.8。教程中的示例和实践不会使用未来发行版中的优化建议。

重复注解

当你想在声明或类型上使用同样的注解其实有很多方法。在Java SE 8 中，重复注解可以满足你的需要。

比如：你想实现一个时间服务，该服务让你的方法可以在指定的时间或者固定的周期运行，就像UNIX的cron表达式。你想让doPeriodicCleanup方法在特定的时间运行，在每个月最后一天和每周五晚上11:00 ，为了设置这两个时间，创建一个@Schedule注解并让它在doPeriodicCleanup 方法上声明2次。如下所示：

@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23")
public void doPeriodicCleanup() { ... }

以上注解应用在方法上。你可以将重复注解运用在普通注解可以运用到的任何地方。比如，你有一个类要处理未授权访问的异常，你可以为该类添加上@Alert注解，一个为管理者，一个为管理员。

@Alert(role="Manager")
@Alert(role="Administrator")
public class UnauthorizedAccessException extends SecurityException { ... }

出于兼容性的原因，重复注解存储在容器注解中，容器注解由Java编译器自动生成。为了让编译器做到这一点，代码中需要两个声明。

步骤1：声明一个可重复注解

注解类型必须用元注解@Repeatable修饰。下面是一个自定义@Schedule注解的例子：

import java.lang.annotation.Repeatable;

@Repeatable(Schedules.class)
public @interface Schedule {
  String dayOfMonth() default "first";
  String dayOfWeek() default "Mon";
  int hour() default 12;
}

圆括号中@Repeatable元注解的值是Java编译器生成的用于存储重复注解的容器注解的类型。在本例中，容器注解类型是Schedules，所以重复注解@Schedule是存储在@Schedules注解中。

在类型声明中运用同一个注解，但之前没有将该注解声明为可重复的，将导致编译错误。

步骤2：声明容器注解类型

容器注解类型必须要有一个数组类型的值，该数组的类型必须是可重复注解的类型。Schedules 容器注解的声明如下：

public @interface Schedules {
    Schedule[] value();
}

检索注解

在反射API中有一些方法可以检索注解。这些方法就是返回一个注解类型，比如 AnnotatedElement.getAnnotation(Class<T>) 仅仅只是返回单一注解，当请求的类上有注解的时候。如果请求类上有多个注解，你首先要检索容器注解，只有这样，代码才能正常工作。在Java SE 8 中还引入了其他的方法可以通过扫描容器注解一次返回多个注解，比如 AnnotatedElement.getAnnotationsByType(Class<T>)。查看AnnotatedElement类规范可以了解所有方法。

设计注意事项

当设计一个注解时，必须注意该注解类型的基数。这个注解可能使用0次、1次还是多次(使用@Repeatable注解)。通过使用@Target可以限制该注解所应用的类型。比如你可以创建一个重复注解类型应用在方法和字段上。仔细设计注解类型非常重要，能确保使用注解的程序员发现该注解的灵活性和强大之处。