Java可重复注解接口（Repeatable Annotation Interfaces）

Java规范参考

详细的解释可以参考Java规范：
https://docs.oracle.com/javase/specs/jls/se19/html/jls-9.html#jls-9.6.3

可重复注解接口介绍

• 可重复注解接口是从Java 1.8版本引入的，表示可以重复出现。
• 一个可重复注解接口A用@Repeatable修饰，并且@Repeatable的元素value 的值指明了一个A的容器注解接口。
• 容器注解接口必须声明一个value()方法，它的返回类型是可重复注解接口类型的数组，例如A[]。
• 在容器注解接口中声明的其它不同于value()的方法，必须有一个默认值。

例如，定义了一个可重复注解接口Name：

package com.thb;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.CLASS;

import java.lang.annotation.Documented;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

@Documented
@Retention(CLASS)
@Target({ TYPE, FIELD })
@Repeatable(Names.class)
public @interface Name {
    String value();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

定义可重复注解Name接口的容器注解接口Names：

package com.thb;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

@Documented
@Retention(RUNTIME)
@Target({ TYPE })
public @interface Names {
    Name[] value();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

• 容器注解接口的保留范围要至少跟可重复注解接口一样长。保留范围用@Retention显式或者隐式声明。
  1）如果容器注解接口的保留范围是java.lang.annotation.RetentionPolicy.SOURCE，那么可重复注解接口的保留范围只能是java.lang.annotation.RetentionPolicy.SOURCE。
  2）如果容器注解接口的保留范围是java.lang.annotation.RetentionPolicy.CLASS，那么可重复注解接口的保留范围可以是java.lang.annotation.RetentionPolicy.CLASS、或者java.lang.annotation.RetentionPolicy.SOURCE。
  3）如果容器注解接口的保留范围是java.lang.annotation.RetentionPolicy.RUNTIME，那么可重复注解接口的保留范围可以是java.lang.annotation.RetentionPolicy.SOURCE、或者java.lang.annotation.RetentionPolicy.CLASS、或者java.lang.annotation.RetentionPolicy.RUNTIME。

• 可重复注解接口可以应用的程序元素类型（用@Target指明），至少要和容器注解接口可以应用的元素类型相同。假设可重复注解接口可以应用的程序元素类型集合是m1，容器注解接口可以应用的程序元素类型集合是m2，那么m2中的每个类型都必须在m1中出现，除非：
  1）如果m2中的类型是java.lang.annotation.ElementType.ANNOTATION_TYPE，那么下面三种类型必须在m1中至少出现一个：java.lang.annotation.ElementType.ANNOTATION_TYPE、 或者 java.lang.annotation.ElementType.TYPE、或者 java.lang.annotation.ElementType.TYPE_USE
  2）如果m2中的类型是java.lang.annotation.ElementType.TYPE，那么下面两种类型必须在m1中至少出现一个：java.lang.annotation.ElementType.TYPE、或者java.lang.annotation.ElementType.TYPE_USE。
  3）如果m2中的类型是java.lang.annotation.ElementType.TYPE_PARAMETER，那么下面两种类型必须在m1中至少出现一个：java.lang.annotation.ElementType.TYPE_PARAMETER、或者java.lang.annotation.ElementType.TYPE_USE。

• 如果可重复注解接口用java.lang.annotation.Documented注解修饰，那么容器注解接口也必须用java.lang.annotation.Documented修饰。注：但容器注解接口用java.lang.annotation.Documented修饰，可重复注解接口可以不用java.lang.annotation.Documented注解修饰

• 如果可重复注解接口用java.lang.annotation.Inherited注解修饰，那么容器注解接口也必须用java.lang.annotation.Inherited修饰。注：但容器注解接口用java.lang.annotation.Inherited修饰，可重复注解接口可以不用java.lang.annotation.Inherited注解修饰

• @Repeatable语句不能重复出现，因此一个可重复注解接口（即被@Repeatable修饰）只能有一个容器注解接口。

• 一个注解接口最多只能是一个注解接口的容器注解接口。

• 一个注解接口不能声明是它本身的容器注解接口。

• 一个容器注解接口可以有自己的容器注解接口，即：容器注解接口本身也可以是可重复注解接口。