java.lang.annotation.*;

1. Structure chart:

Personality drawing

2. Introduce:

Provides library support for the Java programming language annotation facility.

2.1 Common interface: Annotation

• Annotation:

The common interface extended by all annotation types.

2.2 Enum: ElementType, RetentionPolicy

• ElementType.java

public enum ElementType {
    /** Class, interface (including annotation type), or enum declaration */
    TYPE,

    /** Field declaration (includes enum constants) */
    FIELD,

    /** Method declaration */
    METHOD,

    /** Formal parameter declaration */
    PARAMETER,

    /** Constructor declaration */
    CONSTRUCTOR,

    /** Local variable declaration */
    LOCAL_VARIABLE,

    /** Annotation type declaration */
    ANNOTATION_TYPE,

    /** Package declaration */
    PACKAGE,

    /**
     * Type parameter declaration
     *
     * @since 1.8
     */
    TYPE_PARAMETER,

    /**
     * Use of a type
     *
     * @since 1.8
     */
    TYPE_USE
}

• RetentionPolicy.java

public enum RetentionPolicy {
    /**
     * Annotations are to be discarded by the compiler.
     */
    SOURCE,

    /**
     * Annotations are to be recorded in the class file by the compiler
     * but need not be retained by the VM at run time.  This is the default
     * behavior.
     */
    CLASS,

    /**
     * Annotations are to be recorded in the class file by the compiler and
     * retained by the VM at run time, so they may be read reflectively.
     *
     * @see java.lang.reflect.AnnotatedElement
     */
    RUNTIME
}

2.3 Exception: AnnotationTypeMismatchException, IncompleteAnnotationException

• AnnotationTypeMismatchException extends RuntimeException:

Throws an exception if the type of an annotation changes after compiling (or serializing) the annotation, and the program attempts to access the element of the annotation.

key codes:

public AnnotationTypeMismatchException(Method element, String foundType) {
        super("Incorrectly typed data found for annotation element " + element
              + " (Found data of type " + foundType + ")");
        this.element = element;
        this.foundType = foundType;
    }

• IncompleteAnnotationException extends RuntimeException:

Thrown to indicate that a program has attempted to access an element of an annotation type that was added to the annotation type definition after the annotation was compiled (or serialized). This exception will not be thrown if the new element has a default value.

key codes:

public IncompleteAnnotationException(
            Class<? extends Annotation> annotationType,
            String elementName) {
        super(annotationType.getName() + " missing element " +
              elementName.toString());

        this.annotationType = annotationType;
        this.elementName = elementName;
    }

2.4 Error: AnnotationFormatError

• AnnotationFormatError:

Thrown when the annotation parser attempts to read an annotation from a class file and determines that the annotation is malformed.

2.5 Annotation type: Retention, Target, Document, Inherited, Native[1.8+], Repeatable[1.8+]

• @Retention: where do I save the annotation?

TYPE	EXPLAIN
@Retention(RetentionPolicy.SOURCE)	source √ .class ×
@Retention(RetentionPolicy.CLASS)	[Default] .class √ runtime ×
@Retention(RetentionPolicy.RUNTIME)	.class √ runtime √

Get the annotation in runtime? By reflect.

• @Target:

TYPE	EXPLAIN
@Target(ElementType.TYPE)	Class, interface (including annotation type), or enum declaration
@Target(ElementType.FIELD)	Field declaration (includes enum constants)
@Target(ElementType.METHOD)	Method declaration
@Target(ElementType.PARAMETER)	Formal parameter declaration
@Target(ElementType.CONSTRUCTOR)	Constructor declaration
@Target(ElementType.LOCAL_VARIABLE)	Local variable declaration
@Target(ElementType.ANNOTATION_TYPE)	Annotation type declaration
@Target(ElementType.PACKAGE)	Package declaration
@Target(ElementType.TYPE_PARAMETER)[1.8+]	Type parameter declaration
@Target(ElementType.TYPE_USE)[1.8+]	Use of a type

• @Document: Annotation will be contain in the javadoc.

• @Inherited.

• @Native[1.8+]:

Indicates that a field defining a constant value may be referenced from native code. The annotation may be used as a hint by tools that generate native header files to determine whether a header file is required, and if so, what declarations it should contain.

• @Repeatable[1.8+]: Repeatable annotation.

@Repeatable(Authorities.class)
public @interface Authority {
     String role();
}
 
public @interface Authorities {
    Authority[] value();
}
 
public class RepeatAnnotationUseNewVersion {
    @Authority(role="Admin")
    @Authority(role="Manager")
    public void doSomeThing(){ }
}

3. Example: