11.1.2 Meta-Annotations Explained

Meta-annotations in Java SE 11 are annotations that are applied to other annotations. They provide additional information about how an annotation should be processed or used. Understanding meta-annotations is crucial for creating custom annotations and ensuring they behave as expected.

Key Concepts

1. @Retention

The @Retention meta-annotation specifies how long the annotation should be retained. It has three possible values:

• RetentionPolicy.SOURCE: The annotation is retained only in the source code and is discarded during compilation.
• RetentionPolicy.CLASS: The annotation is retained in the class file but is not available at runtime.
• RetentionPolicy.RUNTIME: The annotation is retained in the class file and is available at runtime through reflection.

Example

        @Retention(RetentionPolicy.RUNTIME)
        public @interface MyAnnotation {
            String value();
        }
    

2. @Target

The @Target meta-annotation specifies the types of elements to which an annotation can be applied. It has several possible values:

• ElementType.TYPE: Can be applied to classes, interfaces, enums, and annotations.
• ElementType.FIELD: Can be applied to fields (including enum constants).
• ElementType.METHOD: Can be applied to methods.
• ElementType.PARAMETER: Can be applied to method parameters.
• ElementType.CONSTRUCTOR: Can be applied to constructors.
• ElementType.LOCAL_VARIABLE: Can be applied to local variables.
• ElementType.ANNOTATION_TYPE: Can be applied to other annotations.
• ElementType.PACKAGE: Can be applied to package declarations.

Example

        @Target(ElementType.METHOD)
        public @interface MyAnnotation {
            String value();
        }
    

3. @Documented

The @Documented meta-annotation indicates that the annotation should be included in the Javadoc documentation of the annotated element.

Example

        @Documented
        public @interface MyAnnotation {
            String value();
        }
    

4. @Inherited

The @Inherited meta-annotation indicates that the annotation should be inherited by subclasses of the annotated class. This meta-annotation applies only to class-level annotations.

Example

        @Inherited
        public @interface MyAnnotation {
            String value();
        }
    

5. @Repeatable

The @Repeatable meta-annotation indicates that the annotation can be applied multiple times to the same element. It requires the definition of a containing annotation that holds the repeated annotations.

Example

        @Repeatable(MyAnnotations.class)
        public @interface MyAnnotation {
            String value();
        }

        public @interface MyAnnotations {
            MyAnnotation[] value();
        }
    

Examples and Analogies

Think of meta-annotations as rules for how annotations should be treated. For example, @Retention is like setting a timer for how long an annotation should be active, @Target is like specifying where an annotation can be placed, @Documented is like adding a note to a document, @Inherited is like passing down a trait to children, and @Repeatable is like allowing multiple entries for the same item.

For instance, if you want to create an annotation that can be used on methods and should be available at runtime, you would use @Target(ElementType.METHOD) and @Retention(RetentionPolicy.RUNTIME). This is like creating a sticky note that can only be attached to methods and will remain visible even after the code is compiled.

By mastering meta-annotations, you can create powerful and flexible custom annotations in Java SE 11, enhancing the readability and maintainability of your code.