> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Java 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.
```java theme={"dark"}
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.
```java theme={"dark"}
// 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.
Tired of Poor Java Skills? Fix That With Deep Grasping!
Learn More
