在某些情况下,您要将相同的注释应用于声明或类型使用。从JavaSE 8版本开始,重复注释使您能够做到这一点。
例如,您正在编写代码以使用定时服务,使您能够在给定时间或某个时间表运行方法,类似于UNIXcron服务。现在你想设置一个计时器来运行一个方法doPeriodicCleanup,在这个月的最后一天和每个星期五晚上11点。要设置运行定时器,创建一个@Schedule注解并将其应用于doPeriodicCleanup方法两次。第一个用途指定一个月的最后一天,第二个用于指定星期五为11p.m.,如下面的代码示例所示:
@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23")
public void doPeriodicCleanup() { ... }
前面的示例将注解应用于方法。您可以在使用标准注解的任何地方重复注释。例如,您有一个用于处理未经授权的访问异常的类。您可以使用一个@Alert注解为管理员manager注解该类,另一个用于管理员admin:
@Alert(role="Manager")
@Alert(role="Administrator")
public class UnauthorizedAccessException extends SecurityException { ... }
出于兼容性原因,重复注释存储在由Java编译器自动生成的容器注解中。为了使编译器执行此操作,在你的代码中两个声明必须要写。
第一步:声明一个可重复的注解类型
注:将相同的注解应用于声明而不首先声明它可重复,导致编译时错误。
该注解类型必须被@Repeatable元注解所标记,以下例子定义了一个注解@Schedule为可重复注解类型:
importjava.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注解中。
第二步:声明包含注解类型
容器注解类型必须具有数组类型的值元素。数组类型的组件类型必须是可重复的注释类型。容器注解类型Schedules的声明如下:
public@interface Schedules {
Schedule[] value();
}
检索注解
Reflection API中有几种可用于检索注解的方法。返回单个注释的方法(如AnnotatedElement.getAnnotationByType(Class))。如果存在所请求类型的一个注解,它们只返回单个注释。如果存在多个请求类型的注解,您可以先获取它们的容器注解来获取它们。这样,旧代码继续运行。在Java SE 8中引入了其他方法,它们通过容器注释进行扫描,以一次返回多个注释,如AnnotatedElement.getAnnotations(Class)。有关所有可用方法的信息,请参阅AnnotatedElement类规范。
设计注意事项
设计注解类型时,您必须考虑该类型注解的基数。现在可以使用注解零次,一次,或者如果注解的类型被标记为@Repeatable多次。也可以通过使用@Target元注解来限制可以使用注解类型的位置。例如,您可以创建只能在方法和字段上使用的可重复注解类型。重要的是仔细设计注解类型,以确保使用注解的程序员发现它尽可能灵活和强大。