These constants are used with the {@link Target} meta-annotation type - * to specify where it is legal to use an annotation type. + *
The syntactic locations where annotations may appear are split into + * declaration contexts , where annotations apply to declarations, and + * type contexts , where annotations apply to types used in + * declarations and expressions. + * + *
The constants {@link #ANNOTATION_TYPE} , {@link #CONSTRUCTOR} , {@link + * #FIELD} , {@link #LOCAL_VARIABLE} , {@link #METHOD} , {@link #PACKAGE} , + * {@link #PARAMETER} , {@link #TYPE} , and {@link #TYPE_PARAMETER} correspond + * to the declaration contexts in JLS 9.6.4.1. + * + *
For example, an annotation whose type is meta-annotated with + * {@code @Target(ElementType.FIELD)} may only be written as a modifier for a + * field declaration. + * + *
The constant {@link #TYPE_USE} corresponds to the 15 type contexts in JLS + * 4.11, as well as to two declaration contexts: type declarations (including + * annotation type declarations) and type parameter declarations. + * + *
For example, an annotation whose type is meta-annotated with + * {@code @Target(ElementType.TYPE_USE)} may be written on the type of a field + * (or within the type of the field, if it is a nested, parameterized, or array + * type), and may also appear as a modifier for, say, a class declaration. + * + *
The {@code TYPE_USE} constant includes type declarations and type + * parameter declarations as a convenience for designers of type checkers which + * give semantics to annotation types. For example, if the annotation type + * {@code NonNull} is meta-annotated with + * {@code @Target(ElementType.TYPE_USE)}, then {@code @NonNull} + * {@code class C {...}} could be treated by a type checker as indicating that + * all variables of class {@code C} are non-null, while still allowing + * variables of other classes to be non-null or not non-null based on whether + * {@code @NonNull} appears at the variable's declaration. * * @author Joshua Bloch * @since 1.5 + * @jls 9.6.4.1 @Target + * @jls 4.1 The Kinds of Types and Values */ public enum ElementType { /** Class, interface (including annotation type), or enum declaration */ diff --git a/src/share/classes/java/lang/annotation/Target.java b/src/share/classes/java/lang/annotation/Target.java --- a/src/share/classes/java/lang/annotation/Target.java +++ b/src/share/classes/java/lang/annotation/Target.java @@ -26,33 +26,42 @@ package java.lang.annotation; /** - * Indicates the kinds of program element to which an annotation type - * is applicable. If a Target meta-annotation is not present on an - * annotation type declaration, the declared type may be used on any - * program element. If such a meta-annotation is present, the compiler - * will enforce the specified usage restriction. + * Indicates the contexts in which an annotation type is applicable. The + * declaration contexts and type contexts in which an annotation type may be + * applicable are specified in JLS 9.6.4.1, and denoted in source code by enum + * constants of {@link ElementType java.lang.annotation.ElementType}. * - * For example, this meta-annotation indicates that the declared type is - * itself a meta-annotation type. It can only be used on annotation type - * declarations: + *
If an {@code @Target} meta-annotation is not present on an annotation type + * {@code T} , then an annotation of type {@code T} may be written as a + * modifier for any declaration except a type parameter declaration. + * + *
If an {@code @Target} meta-annotation is present, the compiler will enforce + * the usage restrictions indicated by {@code ElementType} + * enum constants, in line with JLS 9.7.4. + * + *
For example, this {@code @Target} meta-annotation indicates that the + * declared type is itself a meta-annotation type. It can only be used on + * annotation type declarations: *
* @Target(ElementType.ANNOTATION_TYPE)
* public @interface MetaAnnotationType {
* ...
* }
*
- * This meta-annotation indicates that the declared type is intended solely
- * for use as a member type in complex annotation type declarations. It
- * cannot be used to annotate anything directly:
+ *
+ * This {@code @Target} meta-annotation indicates that the declared type is + * intended solely for use as a member type in complex annotation type + * declarations. It cannot be used to annotate anything directly: *
* @Target({})
* public @interface MemberType {
* ...
* }
*
- * It is a compile-time error for a single ElementType constant to
- * appear more than once in a Target annotation. For example, the
- * following meta-annotation is illegal:
+ *
+ * It is a compile-time error for a single {@code ElementType} constant to + * appear more than once in an {@code @Target} annotation. For example, the + * following {@code @Target} meta-annotation is illegal: *
* @Target({ElementType.FIELD, ElementType.METHOD, ElementType.FIELD})
* public @interface Bogus {
@@ -61,7 +70,8 @@
*
*
* @since 1.5
- * @jls 9.6.3.1 @Target
+ * @jls 9.6.4.1 @Target
+ * @jls 9.7.4 Where Annotations May Appear
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)