Meta-Annotations & Retention

## What is an annotation? An **annotation** is a marker attached to code (a class, method, field, parameter, etc.), written with an `@` sign, e.g. `@Override`. It is *metadata*: information about the code that does nothing by itself. Some other party (the compiler, a framework, a tool) reads it and acts on it. ## What is a meta-annotation? A **meta-annotation** is an annotation placed on the *declaration of another annotation*. The standard ones live in `java.lang.annotation`: `@Retention`, `@Target`, `@Documented`, `@Inherited`, `@Repeatable`. They configure how the annotation you are defining behaves. `@Retention` is the most important one. ## What @Retention controls `@Retention` decides **how long the annotation survives** as your code moves through three stages: source code -> compiled `.class` bytecode -> running JVM. Its value is one of the `RetentionPolicy` enum constants. - **SOURCE**: The annotation exists only in the `.java` source. The compiler reads it (if it wants) and then *throws it away* — it never appears in the `.class` file. Use this for things only the compiler or source tools need: `@Override`, `@SuppressWarnings`, and Lombok annotations like `@Getter` (Lombok runs during compilation, generates code, then the annotation is gone). - **CLASS**: The annotation is written into the `.class` bytecode file, but when the JVM loads the class it *does not* keep the annotation in memory, so **reflection cannot see it**. This is the **default** — if you write a custom annotation and omit `@Retention`, you get CLASS. Tools that read bytecode directly (bytecode weavers, some analyzers) can still see it. - **RUNTIME**: The annotation is in the bytecode *and* the JVM loads it into the runtime class metadata, so it is **visible to reflection** while the program runs. This is what frameworks need: Spring, JUnit, Jackson, JPA all scan classes with reflection (`clazz.getAnnotation(...)`, `isAnnotationPresent(...)`), so their annotations are RUNTIME. ## How retention is checked At runtime you read annotations through the **Reflection API**: methods like `Class.getAnnotation(MyAnno.class)`, `Method.getAnnotations()`, `isAnnotationPresent(...)`. These return data **only for RUNTIME-retained** annotations. A SOURCE or CLASS annotation will make these methods return `null`/empty with no error — a classic silent bug. ## Choosing a policy Rule of thumb: if anything reads the annotation via reflection at runtime, use RUNTIME. If only the compiler/source tooling needs it, use SOURCE. CLASS is rarely chosen on purpose; you mostly get it by accident as the default. Picking too broad wastes a little space and keeps metadata you do not need; picking too narrow is worse because reflection quietly returns nothing. ## Worked example ```java import java.lang.annotation.*; @Retention(RetentionPolicy.RUNTIME) @interface Audited {} class Service { @Audited void pay() {} } // elsewhere: Method m = Service.class.getDeclaredMethod("pay"); boolean isAudited = m.isAnnotationPresent(Audited.class); // true ONLY because RUNTIME ``` If `@Audited` had no `@Retention` (defaulting to CLASS) or SOURCE, `isAnnotationPresent` would return `false`.