Unused.java revision 59b2e6871c65f58fdad78cd7229c292f6a177578
159b2e6871c65f58fdad78cd7229c292f6a177578Scott Bartapackage checkers.quals; 259b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta 359b2e6871c65f58fdad78cd7229c292f6a177578Scott Bartaimport static java.lang.annotation.ElementType.FIELD; 459b2e6871c65f58fdad78cd7229c292f6a177578Scott Bartaimport java.lang.annotation.*; 559b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta 659b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta/** 759b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * Declares that the field may not be accessed if the receiver is of the 859b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * specified qualifier type (or any supertype). 959b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 1059b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * This property is verified by the checker that type-checks the {@code 1159b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * when} element value qualifier. 1259b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 1359b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * <p><b>Example</b> 1459b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * Consider a class, {@code Table}, with a locking field, {@code lock}. The 1559b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * lock is used when a {@code Table} instance is shared across threads. When 1659b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * running in a local thread, the {@code lock} field ought not to be used. 1759b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 1859b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * You can declare this behavior in the following way: 1959b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 2059b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * <pre><code> 2159b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * class Table { 2259b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * private @Unused(when=LocalToThread.class) final Lock lock; 2359b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * ... 2459b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * } 2559b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * </code></pre> 2659b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 2759b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * The checker for {@code @LocalToThread} would issue an error for the following code: 2859b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 2959b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * <pre> @LocalToThread Table table = ...; 3059b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * ... table.lock ...; 3159b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * </pre> 3259b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * 3359b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta */ 3459b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta@Documented 3559b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta@Retention(RetentionPolicy.RUNTIME) 3659b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta@Target({FIELD}) 3759b2e6871c65f58fdad78cd7229c292f6a177578Scott Bartapublic @interface Unused { 3859b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta /** 3959b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * The field that is annotated with @Unused may not be accessed via a 4059b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta * receiver that is annotated with the "when" annotation. 4159b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta */ 4259b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta Class<? extends Annotation> when(); 4359b2e6871c65f58fdad78cd7229c292f6a177578Scott Barta} 44