Retention Annotation

The @Retention annotation is a meta-annotation in Java that dictates the lifecycle of a custom annotation. It specifies the exact point at which an annotation is discarded during the compilation and execution phases, determining its availability in the source code, the compiled bytecode (.class file), or the Java Virtual Machine (JVM) memory space at runtime.

Syntax

The @Retention annotation accepts a single argument of type java.lang.annotation.RetentionPolicy, which is an enum defining the three possible retention strategies.

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.RUNTIME)
public @interface MyCustomAnnotation {
    String value() default "";
}

Retention Policies

The RetentionPolicy enum defines the following three constants, representing escalating levels of persistence:

1. RetentionPolicy.SOURCE

Annotations marked with SOURCE are retained only in the source code (.java files).

• Compiler Behavior: The Java compiler parses these annotations into the Abstract Syntax Tree (AST) for processing by annotation processors, but strips them entirely before generating the bytecode.
• Bytecode Presence: Absent.
• Runtime Availability: Absent.

2. RetentionPolicy.CLASS

Annotations marked with CLASS are recorded in the compiled class file but are not loaded into the JVM at runtime.

• Compiler Behavior: The compiler writes the annotation data into the RuntimeInvisibleAnnotations attribute. According to the Java Virtual Machine Specification (JVMS), this is a variable-length attribute located in the attributes table of a ClassFile, field_info, or method_info structure.
• Bytecode Presence: Present.
• Runtime Availability: Absent. The JVM class loader ignores these annotations when loading the class into memory, meaning they cannot be accessed via the Reflection API.
• Note: If a custom annotation is declared without an explicit @Retention meta-annotation, CLASS is the default behavior.

3. RetentionPolicy.RUNTIME

Annotations marked with RUNTIME are preserved through the entire compilation and execution lifecycle.

• Compiler Behavior: The compiler writes the annotation data into the RuntimeVisibleAnnotations attribute, which is located in the attributes table of the corresponding ClassFile, field_info, or method_info structure.
• Bytecode Presence: Present.
• Runtime Availability: Present. The JVM retains these annotations in memory. They are accessible during program execution via the java.lang.reflect.AnnotatedElement interface (e.g., Class.getAnnotations(), Method.getAnnotation()).

Internal Mechanics

The @Retention annotation itself is defined with a @Target(ElementType.ANNOTATION_TYPE), meaning it can only be applied to other annotation declarations. It cannot be applied to classes, methods, or fields directly.

// Internal JDK definition of @Retention
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
    RetentionPolicy value();
}

Because @Retention is evaluated by the compiler and the JVM’s class loader, attempting to read a SOURCE or CLASS retained annotation using Reflection at runtime will yield a null result, as the metadata simply does not exist in the JVM’s runtime data areas.

Master Java with Deep Grasping Methodology!

Learn More