Java Meta-Annotationen: @Retention, @Target, @Repeatable

Eine Meta-Annotation ist eine Annotation, die Sie auf eine Annotationsdeklaration setzen. Sie konfigurieren, wie sich diese Annotation verhält: wie lange sie erhalten bleibt, wo sie verwendet werden darf, ob Unterklassen sie erben und ob Sie sie mehr als einmal anwenden können. In java.lang.annotation gibt es fünf davon, und jeder Annotationstyp, den Sie schreiben, wird mindestens die ersten beiden verwenden.

Die fünf:

@Retention — steuert, ob die Annotation in .class-Dateien und zur Laufzeit erhalten bleibt.
@Target — schränkt ein, auf welche Arten von Programmelementen die Annotation angewendet werden kann.
@Documented — lässt die Annotation im generierten Javadoc erscheinen.
@Inherited — bewirkt, dass Unterklassen Annotationen auf Klassenebene von ihrer Oberklasse erben.
@Repeatable — erlaubt, dieselbe Annotation mehr als einmal auf dasselbe Element anzuwenden.

`@Retention`

@Retention wählt einen von drei RetentionPolicy-Werten:

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

@Retention(RetentionPolicy.SOURCE)        // stripped by javac; never in bytecode
@interface SuppressEvenMoreWarnings { }

@Retention(RetentionPolicy.CLASS)         // in bytecode; not loaded by the VM (the default)
@interface BytecodeOnly { }

@Retention(RetentionPolicy.RUNTIME)       // in bytecode and accessible via reflection
@interface MyRuntimeMarker { }

Die richtige Wahl hängt vom Verbraucher ab:

Der Compiler ist der Verbraucher (Override-Prüfungen, Warnungsunterdrückung, Lint) → SOURCE.
Ein Bytecode-Verarbeitungswerkzeug, JIT-Optimierer oder Post-Compile-Analyser ist der Verbraucher → CLASS.
Ein Framework liest die Annotation zur Laufzeit über Reflection (DI, ORM, JSON-Binding) → RUNTIME.

RUNTIME ist die großzügigste Option — sie ist auch die kostspieligste, da jede Annotation, die erhalten bleibt, Bytes zur Klassendatei hinzufügt und beim Lookup einen kleinen Reflection-Overhead verursacht.

`@Target`

@Target schränkt ein, wo die Annotation platziert werden kann. Ihr Wert ist ein Array von ElementType-Konstanten:

import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Audited { }                                   // only on methods or constructors

@Target(ElementType.TYPE)
@interface Entity { }                                    // only on classes/interfaces/enums

@Target({})
@interface CannotBeApplied { }                           // exists only as a type — can't be used to annotate anything

Die ElementType-Werte, denen Sie begegnen werden:

TYPE — Klasse, Interface, Enum, Annotation.
METHOD, CONSTRUCTOR, FIELD, PARAMETER, LOCAL_VARIABLE.
ANNOTATION_TYPE — für Meta-Annotationen wie die in diesem Kapitel.
PACKAGE — in package-info.java.
TYPE_USE (Java 8+) — jede Verwendung eines Typs, einschließlich Casts ((@NonNull String) o), extends-Klauseln, generische Argumente. Wird von Nullability-Checkern wie dem Checker Framework verwendet.
TYPE_PARAMETER (Java 8+) — nur bei <T extends ...>-Deklarationen.
MODULE (Java 9+) — in module-info.java.
RECORD_COMPONENT (Java 16+) — bei den Parametern eines Record-Headers.

Wenn Sie @Target ganz weglassen, kann die Annotation fast überall verwendet werden — nützlich für sehr allgemeine Marker, aber einschränkend für alles andere. Setzen Sie fast immer ein explizites @Target.

`@Documented`

Standardmäßig werden Annotationen nicht im Javadoc der Elemente angezeigt, die sie dekorieren. @Documented sorgt dafür, dass eine Annotation in die Dokumentation aufgenommen wird:

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface ApiNote {
  String value();
}

Wenn eine Methode @ApiNote("rate-limited to 5 rps") trägt, wird Javadoc diese Annotation in den gerenderten Docs anzeigen. Ohne @Documented existiert die Annotation zur Laufzeit, ist aber in der generierten Dokumentation unsichtbar. Fügen Sie @Documented zu allem hinzu, das Benutzer Ihrer Bibliothek sehen sollen.

`@Inherited`

@Inherited gilt nur für Annotationen, die auf TYPE (Klassen) abzielen. Es bedeutet: Wenn eine Klasse annotiert ist, werden ihre Unterklassen ebenfalls als annotiert behandelt. Reflections getAnnotation(...) wird die Oberklassen-Kette hinaufgehen und die Annotation finden.

@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Auditable { }

@Auditable
class Account { }

class SavingsAccount extends Account { }                 // also "auditable" via inheritance

Einschränkungen:

Es wird nur die Oberklassen-Kette durchlaufen — Interfaces propagieren keine Annotationen, auch nicht mit @Inherited. class Foo implements Auditable { } bewirkt nicht, dass Foo ein @Auditable vom Interface erbt.
Es betrifft nur, wie Reflection Annotationen auf Klassen meldet. Methoden, Felder und Parameter erben niemals Annotationen von überschriebenen Mitgliedern.

Die meisten Frameworks bevorzugen heutzutage explizite, wiederholte Annotationen gegenüber Vererbung, weil die Regeln einfacher sind. Verwenden Sie @Inherited nur, wenn "alles, was eine Marker-Klasse erweitert, ebenfalls markiert ist" wirklich das ist, was Sie wollen.

`@Repeatable`

Vor Java 8 konnte man dieselbe Annotation nicht zweimal auf dasselbe Element anwenden. @Repeatable hebt diese Einschränkung auf, aber die Mechanik erfordert Sorgfalt. Sie deklarieren eine Container-Annotation, die ein Array der wiederholten Werte enthält, und verweisen mit @Repeatable auf den Container:

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Schedules { Schedule[] value(); }            // the container

@Repeatable(Schedules.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Schedule { String cron(); }                  // the repeated annotation

class Reports {
  @Schedule(cron = "0 9 * * MON")
  @Schedule(cron = "0 9 * * FRI")
  public void weekly() { /* ... */ }
}

Regeln:

Das value-Element des Containers muss ein Array des wiederholten Annotationstyps sein.
Der Container und die wiederholte Annotation sollten dieselbe Retention und mindestens dieselben Targets haben.
Wenn die wiederholte Annotation @Documented ist, muss der Container ebenfalls @Documented sein — und ebenso für @Inherited. Der Compiler lehnt einen Konflikt mit containing annotation interface ... is not @Documented ab. Halten Sie ihre Meta-Annotationen synchron.
Zur Laufzeit bündelt der Compiler wiederholte Verwendungen in eine einzige Container-Annotation. Reflection hat sowohl getAnnotation(Schedule.class) (gibt das einzelne Container-Element zurück, wenn es zwei gibt) als auch getAnnotationsByType(Schedule.class) (gibt das Array direkt zurück). Verwenden Sie die zweite Form bei @Repeatable-Annotationen.

Ein ausgearbeitetes Beispiel: alle fünf Meta-Annotationen auf einer echten Annotation

Das Beispiel erstellt ein kleines Annotationssystem von Grund auf: ein @Schedule, das RUNTIME-sichtbar, nur für Methoden, dokumentiert und wiederholbar ist; ein Marker @Module, der von Unterklassen geerbt wird. Die Main-Methode liest sie dann über Reflection.

java— editable, runs on the server

import java.lang.annotation.*;
import java.lang.reflect.Method;
import java.util.Arrays;

public class MetaAnnotationsDemo {

// 1. A documented, runtime-visible, repeatable annotation
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.METHOD)
  @Documented
  @Repeatable(Schedules.class)
  @interface Schedule { String cron(); }

@Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.METHOD)
  @Documented
  @interface Schedules { Schedule[] value(); }

// 2. An inheritable class-level annotation
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.TYPE)
  @Inherited
  @interface Module { String name(); }

@Module(name = "reports")
  static class ReportingBase { }

static class WeeklyReports extends ReportingBase {     // inherits @Module via @Inherited
    @Schedule(cron = "0 9 * * MON")
    @Schedule(cron = "0 9 * * FRI")
    public void runWeekly() { }

@Schedule(cron = "0 0 * * *")
    public void runDaily() { }
  }

// 3. An interface annotation — NOT inherited even with @Inherited
  interface IModule { }
  @Module(name = "ignored")
  interface AnnotatedInterface { }
  static class WithInterface implements AnnotatedInterface { }

public static void main(String[] args) throws Exception {
    // 1. @Module is found on the subclass via @Inherited
    Module m = WeeklyReports.class.getAnnotation(Module.class);
    System.out.println("1. @Module on subclass (inherited) -> " + (m == null ? "null" : m.name()));

// 2. Interfaces do NOT propagate annotations
    Module mIface = WithInterface.class.getAnnotation(Module.class);
    System.out.println("2. @Module via interface inheritance -> " + mIface);

// 3. Repeated @Schedule on runWeekly — use getAnnotationsByType
    Method weekly = WeeklyReports.class.getMethod("runWeekly");
    Schedule[] weeklySchedules = weekly.getAnnotationsByType(Schedule.class);
    System.out.println("\n3. @Schedule on runWeekly (count = " + weeklySchedules.length + "):");
    for (Schedule s : weeklySchedules) System.out.println("   cron = " + s.cron());

// 4. Single @Schedule on runDaily — both lookup forms work
    Method daily = WeeklyReports.class.getMethod("runDaily");
    Schedule one = daily.getAnnotation(Schedule.class);
    System.out.println("\n4. @Schedule on runDaily:");
    System.out.println("   getAnnotation -> cron = " + one.cron());
    System.out.println("   getAnnotationsByType count -> " + daily.getAnnotationsByType(Schedule.class).length);

// 5. What getAnnotation sees on a repeated method: the container, not Schedule
    System.out.println("\n5. Repeated case via getAnnotation:");
    System.out.println("   weekly.getAnnotation(Schedule.class) -> " + weekly.getAnnotation(Schedule.class));
    System.out.println("   weekly.getAnnotation(Schedules.class) -> " + weekly.getAnnotation(Schedules.class));

// 6. Reading the meta-annotations on @Schedule itself
    System.out.println("\n6. Meta-annotations on @Schedule:");
    for (Annotation a : Schedule.class.getAnnotations()) System.out.println("   " + a);
  }
}

Was man aus der Ausführung mitnehmen sollte:

@Module wurde auf der Oberklasse ReportingBase deklariert, aber Reflection fand es auf WeeklyReports, weil die Annotation @Inherited trägt. Der Lookup durchläuft die Klassenhierarchie, bis er die Annotation findet oder keine Oberklassen mehr vorhanden sind.
Der Interface-Fall zeigte die Grenze der Vererbung: WithInterface implementiert AnnotatedInterface, das @Module hat, aber getAnnotation(Module.class) gab null zurück. @Inherited durchläuft nur extends, niemals implements. Dies verwirrt viele Einsteiger; wenn Sie Annotationssichtbarkeit über Interfaces hinweg benötigen, müssen Sie den Typbaum selbst durchlaufen.
runWeekly trug zwei @Schedule-Annotationen. getAnnotationsByType(Schedule.class) gab ein Array der Länge 2 zurück — die richtige Art, wiederholte Annotationen zu lesen. Der Container @Schedules ist für Benutzercode unsichtbar, wenn Sie bei getAnnotationsByType bleiben.
Der Fall mit einer einzigen @Schedule bei runDaily war symmetrisch: getAnnotation(Schedule.class) funktionierte, weil es keinen Container gab, und getAnnotationsByType gab ein Array der Länge 1 zurück. Beide Formen sind in Ordnung, wenn Sie die Multiplizität kennen.
Die Zeilen "repeated case via getAnnotation" enthüllten die Falle. Bei runWeekly gab getAnnotation(Schedule.class) null zurück — die tatsächliche Annotation in der Klassendatei ist ein synthetisierter @Schedules-Container, kein Schedule. Der Zugriff auf den Container über getAnnotation(Schedules.class) funktioniert. Die Regel: Für jede @Repeatable-Annotation immer getAnnotationsByType verwenden, damit die beiden Fälle (ein Vorkommen vs. viele) identisch aussehen.

Ihre Auswahl treffen

Wenn Sie eine neue Annotation schreiben, entscheiden Sie alle fünf auf einmal:

Wer muss sie lesen? → @Retention.
Wo darf sie erscheinen? → @Target.
Sollen Benutzer sie im Javadoc sehen? → @Documented oder nicht.
Sollen Unterklassen sie erben? → @Inherited für Marker auf Klassenebene wie @Auditable. Weglassen für Annotationen auf Methodenebene.
Soll sie mehr als einmal angewendet werden? → @Repeatable wenn und nur wenn Sie wirklich Multiplizität benötigen.

Das Standard-Skelett für eine zur Laufzeit sichtbare Methoden-Annotation:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
@interface MyAnnotation { /* elements */ }

Das nächste Kapitel — Benutzerdefinierte Annotationen — verwendet genau dieses Muster, um eine von Grund auf zu erstellen und sie mit Reflection zu verwenden. Für die Annotationen, die das JDK mitliefert, siehe Eingebaute Annotationen; für die oben verwendete Reflection API siehe Annotationen mit Reflection lesen.

Übungen

Übung

Sie deklarieren `@Tagged` mit `@Inherited` und `@Target(ElementType.TYPE)`. `interface Marker {}` ist mit `@Tagged` annotiert, und `class Concrete implements Marker {}`. Was gibt `Concrete.class.getAnnotation(Tagged.class)` zurück?

`null` — `@Inherited` durchläuft nur die `extends`-Kette (Oberklassen). Annotationen auf Interfaces werden niemals von implementierenden Klassen geerbt, auch wenn die Annotation `@Inherited` trägtDie `@Tagged`-Annotationsinstanz von `Marker`, weil `@Inherited` sowohl `extends` als auch `implements` durchläuft`null` — `@Inherited` wird stillschweigend ignoriert, wenn `@Target` der Annotation `TYPE` istEs wirft eine `IllegalAnnotationException`, weil Annotationen nicht auf Interfaces platziert werden können