When designing a custom annotation, how do @Retention and @Target shape whether and where it can be used, and what are the consequences of getting them wrong?

## The problem these solve Declaring `@interface Foo {}` isn't enough: you must also say **how long Foo survives** and **where it's allowed to appear**. Those are set by two **meta-annotations** (annotations placed on the annotation declaration): `@Retention` and `@Target`. ## `@Retention` — the lifetime `@Retention(RetentionPolicy.X)` chooses one of three policies, an ascending lifetime: | Policy | Kept in source? | Kept in .class file? | Visible via reflection at runtime? | Typical use | |---|---|---|---|---| | `SOURCE` | yes | **no** | no | source-only tools: Lombok, `@Override`-style compiler hints, annotation processors that run at compile time | | `CLASS` (**default**) | yes | yes | **no** | bytecode tools that read .class files but not reflection; rarely what you want for your own runtime logic | | `RUNTIME` | yes | yes | **yes** | any framework that inspects annotations at runtime via reflection (Spring, JPA, Jackson, Bean Validation) | Key consequence: **only `RUNTIME` is readable with reflection** (`method.getAnnotation(Foo.class)`). If you forget `@Retention` entirely, you get `CLASS`, so `getAnnotation` returns `null` and your framework silently does nothing, one of the most common custom-annotation bugs. ## `@Target` — where it may appear `@Target({ElementType...})` is an array of the program elements the annotation may be placed on. The main `ElementType` values: - `TYPE` — class, interface, enum, annotation, **record**. - `METHOD`, `CONSTRUCTOR`. - `FIELD`, `PARAMETER`, `LOCAL_VARIABLE`. - `ANNOTATION_TYPE` — only on other annotations (meta-annotations). - `PACKAGE`, `MODULE`. - `TYPE_PARAMETER` (Java 8+) — on a generic type variable `<T>`. - `TYPE_USE` (Java 8+) — on **any use of a type**, e.g. `@NonNull String`, `List<@NonNull T>`, casts, `new` expressions. This is what powers pluggable type checkers. - `RECORD_COMPONENT` (Java 16+) — on a record's components. **If you omit `@Target`, the annotation can be applied to almost any declaration.** Adding `@Target` *restricts* it: the compiler then **rejects** the annotation anywhere not in the list. So a too-narrow `@Target` blocks legitimate placements; a missing/too-broad one lets it leak onto elements your processing code never expects. ## How they interact with consumption Design these to match the **consumer**: - A runtime framework reading via reflection → `@Retention(RUNTIME)` is mandatory. - A compile-time annotation processor (JSR 269) → `SOURCE` is enough (and keeps the annotation out of the artifact). - An annotation that decorates fields for ORM mapping → `@Target(FIELD)` (or `{FIELD, METHOD}` to allow property access). ## Other relevant meta-annotations - `@Documented` — include the annotation in generated Javadoc. - `@Inherited` — a class-level annotation is inherited by subclasses (only for `TYPE`, and only via `getAnnotations`, not interfaces). - `@Repeatable(Container.class)` — allow the same annotation multiple times on one element (Java 8+), backed by an auto-generated container annotation. ## Worked example ```java import java.lang.annotation.*; @Retention(RetentionPolicy.RUNTIME) // readable by reflection @Target({ElementType.METHOD, ElementType.TYPE}) @Documented public @interface Audited { String action(); String[] roles() default {}; } ``` Consumed at runtime: ```java Audited a = m.getAnnotation(Audited.class); // null unless RUNTIME retention if (a != null) log(a.action(), a.roles()); ``` ## Pitfalls and consequences - **Forgot `@Retention`** → defaults to `CLASS` → reflection finds nothing → framework silently inert. - **Too-narrow `@Target`** → compile error when applied to a valid-by-intent site. - **No `@Target`** → annotation can land on unexpected elements; processing code may NPE or misbehave. - **Expecting `@Inherited` to cover interfaces or methods** → it only applies to class-level annotations inherited by subclasses.