1package checkers.quals;
2
3import java.lang.annotation.*;
4
5/**
6 * A meta-annotation to specify all the qualifiers that the given qualifier
7 * is a subtype of.  This provides a declarative way to specify the type
8 * qualifier hierarchy.  (Alternatively, the hierarchy can be defined
9 * procedurally by subclassing {@link checkers.types.QualifierHierarchy} or
10 * {@link checkers.types.TypeHierarchy}.)
11 *
12 * <p>
13 * Example:
14 * <pre> @SubtypeOf( { Nullable.class } )
15 * public @interface NonNull { }
16 * </pre>
17 *
18 * <p>
19 *
20 * If a qualified type is a subtype of the same type without any qualifier,
21 * then use <code>Unqualified.class</code> in place of a type qualifier
22 * class.  For example, to express that <code>@Encrypted <em>C</em></code>
23 * is a subtype of <code><em>C</em></code> (for every class
24 * <code><em>C</em></code>), and likewise for <code>@Interned</code>, write:
25 *
26 * <pre> @SubtypeOf(Unqualified.class)
27 * public @interface Encrypted { }
28 *
29 * &#64;SubtypeOf(Unqualified.class)
30 * public @interface Interned { }
31 * </pre>
32 *
33 * <p>
34 *
35 * For the root type qualifier in the qualifier hierarchy (i.e., the
36 * qualifier that is a supertype of all other qualifiers in the given
37 * hierarchy), use an empty set of values:
38 *
39 * <pre> @SubtypeOf( { } )
40 * public @interface Nullable { }
41 *
42 * &#64;SubtypeOf( {} )
43 * public @interface ReadOnly { }
44 * </pre>
45 *
46 * <p>
47 * Together, all the @SubtypeOf meta-annotations fully describe the type
48 * qualifier hierarchy.
49 * No @SubtypeOf meta-annotation is needed on (or can be written on) the
50 * Unqualified pseudo-qualifier, whose position in the hierarchy is
51 * inferred from the meta-annotations on the explicit qualifiers.
52 */
53@Documented
54@Retention(RetentionPolicy.RUNTIME)
55@Target(ElementType.ANNOTATION_TYPE)
56public @interface SubtypeOf {
57    /** An array of the supertype qualifiers of the annotated qualifier **/
58    Class<? extends Annotation>[] value();
59}
60