1package checkers.quals;
2
3import static java.lang.annotation.ElementType.FIELD;
4import java.lang.annotation.*;
5
6/**
7 * Declares that the field may not be accessed if the receiver is of the
8 * specified qualifier type (or any supertype).
9 *
10 * This property is verified by the checker that type-checks the {@code
11 * when} element value qualifier.
12 *
13 * <p><b>Example</b>
14 * Consider a class, {@code Table}, with a locking field, {@code lock}.  The
15 * lock is used when a {@code Table} instance is shared across threads.  When
16 * running in a local thread, the {@code lock} field ought not to be used.
17 *
18 * You can declare this behavior in the following way:
19 *
20 * <pre><code>
21 * class Table {
22 *   private @Unused(when=LocalToThread.class) final Lock lock;
23 *   ...
24 * }
25 * </code></pre>
26 *
27 * The checker for {@code @LocalToThread} would issue an error for the following code:
28 *
29 * <pre>  @LocalToThread Table table = ...;
30 *   ... table.lock ...;
31 * </pre>
32 *
33 */
34@Documented
35@Retention(RetentionPolicy.RUNTIME)
36@Target({FIELD})
37public @interface Unused {
38    /**
39     * The field that is annotated with @Unused may not be accessed via a
40     * receiver that is annotated with the "when" annotation.
41     */
42    Class<? extends Annotation> when();
43}
44