Java Annotation Processing | W3Docs Learn Java

Annotation Processing ist ein Erweiterungspunkt in javac. Man schreibt eine Klasse — einen Annotation Processor — den der Compiler während der Kompilierung aufruft, ihm die bisher gesehenen Elemente übergibt und auf ihn wartet. Der Processor kann zwei nützliche Dinge tun: den annotierten Code validieren (Fehler oder Warnungen über javac's Diagnosekanal ausgeben) oder neue Quelldateien schreiben, die an derselben Kompilierung teilnehmen.

Frameworks, die man wahrscheinlich bereits verwendet hat, basieren auf diesem Mechanismus:

Lombok schreibt annotierte Klassen um und fügt Getter, Builder sowie equals/hashCode hinzu.
Dagger / Hilt generieren Dependency-Injection-Verdrahtung als Reaktion auf @Inject und @Module.
Hibernates statisches Metamodell generiert Entity_-Klassen für typsichere Criteria-Abfragen.
Auto-Service / Auto-Value generieren Boilerplate-META-INF-Service-Einträge und Value-Klassen.
Micronaut / Quarkus generieren Framework-Verdrahtung zur Buildzeit statt beim Start.

Die Processor-API liegt in javax.annotation.processing und das Sprachmodell in javax.lang.model. Zusammen ermöglichen sie es javac, Drittanbieter-Compile-Time-Tools zu hosten.

Aufbau eines Processors

Ein Processor implementiert javax.annotation.processing.Processor. In der Praxis erweitert man AbstractProcessor und überschreibt process(...):

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import java.util.Set;

@SupportedAnnotationTypes("com.example.Marker")           // which annotations to handle
@SupportedSourceVersion(SourceVersion.RELEASE_21)
public class MarkerProcessor extends AbstractProcessor {

  @Override
  public boolean process(Set<? extends TypeElement> annotations,
                         RoundEnvironment roundEnv) {
    for (Element e : roundEnv.getElementsAnnotatedWith(Marker.class)) {
      processingEnv.getMessager().printMessage(
        javax.tools.Diagnostic.Kind.NOTE,
        "found @Marker on " + e.getSimpleName(),
        e);
    }
    return true;                                          // claim the annotation
  }
}

Die beiden Annotationen auf der Klasse deklarieren, welche Annotationstypen dieser Processor verarbeiten möchte und auf welches Sprachniveau er abzielt. Beide können auch dynamisch aus getSupportedAnnotationTypes() / getSupportedSourceVersion() zurückgegeben werden, falls eine Berechnung notwendig ist.

process wird pro Runde aufgerufen. Jede Runde ist ein Durchlauf durch die Quellen; wenn der Processor neue Dateien erzeugt, werden diese neuen Dateien selbst in einer nachfolgenden Runde verarbeitet. Die Schleife endet, wenn keine Runde mehr neue Dateien produziert.

Das Sprachmodell: kein Reflection

Die erste Überraschung: Im Inneren eines Processors gibt es kein Class<?>. Die Klassen, die verarbeitet werden, wurden noch nicht kompiliert. Stattdessen arbeitet man mit den javax.lang.model.element-Typen:

Element — alles im Quellcode: eine Klasse, Methode, Feld, Parameter, Paket.
TypeElement — eine Klasse, ein Interface oder ein Enum (ein Element, das getQualifiedName() liefert).
ExecutableElement — eine Methode oder ein Konstruktor.
VariableElement — ein Feld, Parameter oder eine lokale Variable.
TypeMirror — ein Typ (wie „der Typ List<String>"), verschieden von dem Element, das ihn deklariert hat.

Diese spiegeln die Laufzeit-Reflection-Typen wider, repräsentieren aber Quellcode, keine geladenen Klassen. Man kann sie traversieren, ihre Annotationen abfragen, ihren umgebenden Scope erfragen. Man kann keine Methoden auf ihnen aufrufen, konstante Ausdrücke beliebig auswerten oder sie instanziieren — es gibt noch keine Instanz.

Um die Element-Werte einer Annotation auszulesen, verwendet man Element.getAnnotation(MyAnn.class) (liefert einen Proxy, ähnlich wie Reflection) oder Element.getAnnotationMirrors() (liefert die strukturelle Form, die man benötigt, wenn der Element-Wert eine Class-Referenz auf einen Typ enthält, der ebenfalls in derselben Runde kompiliert wird).

Den Processor registrieren

Der Compiler muss den Processor finden. Es gibt zwei Wege:

Service-Loader-Datei. Eine Datei namens META-INF/services/javax.annotation.processing.Processor auf dem Classpath des Processors ablegen, deren Inhalt der vollqualifizierte Klassenname des Processors ist, einer pro Zeile. Das ist es, was Tools wie Googles auto-service automatisch generieren.
-processor-Flag. -processor com.example.MarkerProcessor an javac übergeben (oder im Build-Tool konfigurieren — Gradles annotationProcessor-Konfiguration, Mavens <annotationProcessorPaths>).

In Maven und Gradle ist es üblich, den Processor in einem eigenen Modul zu halten und ihn im Hauptmodul mit annotationProcessor (Gradle) / <scope>provided</scope> (Maven) zu referenzieren. Der Processor läuft nur während der Kompilierung und wird nicht zur Laufzeit ausgeliefert.

Dateien generieren

Zwei Ausgaben sind möglich:

Quelldateien — geschrieben via processingEnv.getFiler().createSourceFile(name). Das Ergebnis ist ein JavaFileObject, dessen openWriter() mit Quellcode befüllt wird. Die neue Datei wird in der nächsten Runde kompiliert.
Ressourcendateien — geschrieben via getFiler().createResource(...) für alles, was zur Laufzeit auf dem Classpath landet (z. B. Service-Registrierungen).

Das Muster besteht darin, das Paket und den Namen der neuen Klasse aus dem annotierten Element abzuleiten und dann den Quellcode als String zu templaten:

TypeElement cls = ...;                                     // the annotated class
String pkg = elementUtils.getPackageOf(cls).getQualifiedName().toString();
String genName = cls.getSimpleName() + "Generated";

JavaFileObject src = filer.createSourceFile(pkg + "." + genName, cls);
try (Writer w = src.openWriter()) {
  w.write("package " + pkg + ";\n");
  w.write("public class " + genName + " {\n");
  w.write("  public static String origin() { return \"" + cls.getSimpleName() + "\"; }\n");
  w.write("}\n");
}

Ein echter Processor verwendet typischerweise einen Code-Generator wie JavaPoet (der einen typisierten AST-Builder bereitstellt) statt String-Verkettung. Die Mechanik ist identisch; JavaPoet macht den Quellcode nur lesbarer.

Fehler, Warnungen, Hinweise

Ein Processor meldet Diagnosen über Messager:

processingEnv.getMessager().printMessage(
    Diagnostic.Kind.ERROR,
    "@Marker may only annotate top-level classes",
    element);

Kind.ERROR lässt den Build an der Quelldateiposition dieses Elements fehlschlagen. WARNING, MANDATORY_WARNING und NOTE sind die niedrigeren Stufen. Das Element-Argument sollte immer übergeben werden, wenn möglich — es gibt dem Benutzer eine klickbare Quelldateiposition statt eines Build-Log-Blobs.

Überlegungen zur inkrementellen Kompilierung

Annotation Processors sind eine bekannte Ursache für langsame Builds. Zwei Gründe:

Sie können nicht-inkrementell sein: Wenn dem Processor nicht mitgeteilt wird, welche Quellen erneut verarbeitet werden sollen, verarbeitet das Build-Tool alles neu, sobald sich eine Quelle ändert.
Sie können Parallelismus blockieren: Runden laufen sequenziell.

Gradle hat die Processor-Kategorien isolating und aggregating eingeführt, damit Processors an der inkrementellen Kompilierung teilnehmen können. Ein Processor, der pro annotierter Quelle eine generierte Datei produziert (Dagger macht das für @Component), kann sich als „isolating" deklarieren, und Gradle führt ihn nur für die geänderten Quellen erneut aus. Aggregating-Processors — die über alle annotierten Elemente hinwegschauen, um eine einzelne Registry-Datei zu erzeugen — werden neu gestartet, wenn sich eine annotierte Quelle ändert. Die Kategorie des Processors sollte ehrlich gewählt werden; der Kompromiss liegt zwischen Korrektheit und Geschwindigkeit.

Ein ausgearbeitetes Beispiel: ein Laufzeit-Ersatz für Compile-Time-Verarbeitung

Echtes Annotation Processing erfordert einen Multi-Modul-Build, den javac-Erweiterungspunkt und eine Service-Datei — nichts davon passt in ein einzelnes Programm. Die nächstbeste Demonstration ist ein Laufzeit-Ersatz, der dieselbe Art von Arbeit erledigt: annotierte Klassen durchlaufen, sie validieren und Quelldateien in ein temporäres Verzeichnis schreiben, wie es ein Compile-Time-Processor tun würde.

java— editable, runs on the server

import java.io.IOException;
import java.lang.annotation.*;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.nio.file.*;
import java.util.List;

public class AnnotationProcessingDemo {

// 1. The annotation the (simulated) processor will react to
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.TYPE)
  @interface Generate {
    String suffix() default "Generated";
  }

// 2. A few annotated and unannotated classes
  @Generate
  static class Account {
    long id;
    String holder;
    double balance;
  }

@Generate(suffix = "Helper")
  static class Invoice {
    String number;
    double total;
  }

static class NotAnnotated { int ignored; }

// 3. The 'processor' — same shape as a real one, just at runtime
  static int processOne(Class<?> cls, Path outDir) throws IOException {
    Generate g = cls.getAnnotation(Generate.class);
    if (g == null) return 0;                            // skip unannotated

// 3a. Compile-time-style validation
    if (java.lang.reflect.Modifier.isAbstract(cls.getModifiers())) {
      System.out.println("   ERROR: @Generate cannot annotate abstract class " + cls.getSimpleName());
      return 0;
    }

// 3b. Inspect the 'source' (here: reflection on the loaded class)
    String pkg = cls.getPackageName();
    String genName = cls.getSimpleName() + g.suffix();
    Path file = outDir.resolve(genName + ".java");

StringBuilder src = new StringBuilder();
    src.append("package ").append(pkg).append(";\n");
    src.append("// generated from ").append(cls.getSimpleName()).append("\n");
    src.append("public final class ").append(genName).append(" {\n");
    src.append("  public static java.util.List<String> fields() {\n    return java.util.List.of(");
    String fields = String.join(", ",
        java.util.Arrays.stream(cls.getDeclaredFields())
            .map(f -> "\"" + f.getName() + "\"")
            .toList());
    src.append(fields).append(");\n  }\n");
    src.append("  public static String origin() { return \"").append(cls.getSimpleName()).append("\"; }\n");
    src.append("}\n");

Files.writeString(file, src.toString());
    System.out.println("   wrote " + file.getFileName());
    return 1;
  }

public static void main(String[] args) throws Exception {
    // 1. A fresh temp directory to play the role of getFiler()
    Path outDir = Files.createTempDirectory("apt-demo-");
    System.out.println("1. output directory: " + outDir);

// 2. The candidates for processing
    List<Class<?>> roots = List.of(Account.class, Invoice.class, NotAnnotated.class);
    System.out.println("\n2. classes seen by the processor: " + roots.stream().map(Class::getSimpleName).toList());

// 3. Process them, generating files for the annotated ones
    System.out.println("\n3. processing rounds:");
    int generated = 0;
    for (Class<?> c : roots) {
      System.out.println("-- " + c.getSimpleName() + " @Generate? " + c.isAnnotationPresent(Generate.class));
      generated += processOne(c, outDir);
    }
    System.out.println("\n   generated " + generated + " source file(s)");

// 4. Show the generated content
    System.out.println("\n4. generated files:");
    try (var stream = Files.list(outDir)) {
      for (Path p : stream.toList()) {
        System.out.println("   --- " + p.getFileName() + " ---");
        Files.readString(p).lines().forEach(line -> System.out.println("     " + line));
      }
    }

// 5. Cleanup
    try (var s = Files.list(outDir)) { for (Path p : s.toList()) Files.delete(p); }
    Files.delete(outDir);
    System.out.println("\n5. cleaned up " + outDir);
  }
}

Was man aus dem Lauf mitnehmen kann:

Der Processor hat drei Klassen durchlaufen und auf zwei reagiert — genau die Form von RoundEnvironment.getElementsAnnotatedWith(Generate.class) in einem echten javac-Processor. Die dritte Klasse wurde stillschweigend übersprungen, weil ihre Annotation nicht vorhanden war. Das ist das Modell: Ein Processor verarbeitet pro Runde eine Menge von Elementen und handelt nur für die, die ihn interessieren.
Jede generierte Datei trug das Paket der Quellklasse und einen abgeleiteten Namen. In javax.lang.model berechnet man das Paket aus elementUtils.getPackageOf(typeElement).getQualifiedName() und den Namen aus typeElement.getSimpleName(); hier wurde Class.getPackageName() und Class.getSimpleName() als Analogon verwendet. Das Muster überträgt sich.
Das suffix-Element ermöglichte pro-Verwendungs-Anpassung: Account erzeugte AccountGenerated, Invoice erzeugte InvoiceHelper. Annotation-Elemente sind der Knopf, den man dem Benutzer anbietet; Standardwerte machen den häufigen Fall knapp und benannte Elemente geben präzise Kontrolle, wenn nötig.
Die simulierte Validierung gab eine ERROR:-Zeile für abstrakte Klassen aus. In einem echten Processor wäre das messager.printMessage(Diagnostic.Kind.ERROR, "...", element) und der Build würde an der Quelldateiposition des Benutzers fehlschlagen. Diagnosen sind ein erstklassiges Feature, kein Fallback — sie sollten immer verwendet werden, wenn die Annotation falsch eingesetzt wird, niemals throw.
Der generierte Quellcode enthält nichts Kompliziertes — ein List.of(...) mit Feldnamen und ein origin()-Hilfsmethode. Das ist typisch. Der Wert der Compile-Time-Generierung liegt selten in der Cleverness der Ausgabe; er liegt darin, dass die Ausgabe überhaupt existiert, bevor das Programm läuft, wo die Laufzeit andernfalls Reflection benötigen würde (und deren Kosten zahlen würde).

Wann man einen Processor einsetzen sollte

Ein Processor lohnt sich, wenn:

Man anderenfalls denselben Boilerplate für jede annotierte Klasse von Hand schreiben würde.
Die Arbeit allein aus Quell-Signaturen heraus erledigt werden kann (kein tatsächliches Instanzverhalten erforderlich).
Die Laufzeit-Alternative bei jedem Aufruf Reflection verwenden würde, und diese Kosten sich summieren.

Ein Processor ist das falsche Werkzeug, wenn:

Man eine bestehende Klasse modifizieren möchte. Standard-Processors können nur neue Quelldateien hinzufügen; sie schreiben die annotierte Klasse nicht um. (Lombok schreibt um, indem es sich in javac's interne AST einklinkt, was inoffiziell und fragil ist.)
Die benötigten Metadaten nur zur Laufzeit existieren (Request-Scope, Benutzeridentität, von der Festplatte geladene Konfiguration).
Ein einfaches reflektives Lookup beim Start dieselbe Arbeit in 50 Zeilen erledigen würde.

Die Entscheidung ist dieselbe wie bei jeder Code-Generierung: mehr Arbeit zur Kompilierzeit, weniger Arbeit zur Laufzeit und ein Build, der schwieriger zu debuggen ist. Sorgfältig abwägen.

Ende von Teil 16

Damit schließt der Annotations-Teil des Buches ab. Behandelt wurden: was eine Annotation ist — reine Metadaten, verschieden von Code, der ausgeführt wird — dann die kleine Menge, die die Standardbibliothek bereitstellt, die fünf Meta-Annotationen, die eigene konfigurieren, das Rezept zum Deklarieren einer eigenen Annotation und schließlich die Compile-Time-Processing-API, die Frameworks nutzen, um Annotationen während des Builds zu verarbeiten.

Das mentale Modell, das man mitnehmen sollte: Eine Annotation tut nie etwas. Etwas anderes liest sie und entscheidet sich zu handeln. Dieses „etwas anderes" ist entweder der Compiler (eingebaute Lints), ein Annotation Processor (Compile-Time-Codegenerierung) oder eigener Code via Reflection (Laufzeit-Frameworks). Wenn eine Annotation nicht wie erwartet funktioniert, lautet die erste Frage immer: Wer soll sie eigentlich lesen?

Der nächste Teil des Buches ist Reflection — die Laufzeitseite der API, die man bereits zum Lesen von Annotationen verwendet hat.

Übungen

Übung

Ein Annotation Processor generiert eine 'Module'-Quelldatei, die jede mit `@Service` annotierte Klasse aggregiert. Builds sind langsam, weil jede Quelländerung eine vollständige Neuverarbeitung auslöst. Was ist die geeignetste Gradle-Klassifizierung?

`aggregating` — weil die Ausgabe vom vollständigen Satz annotierter Elemente abhängt (sie 'aggregiert' über diese hinweg). Das Build-Tool kann den Processor nicht sicher überspringen, wenn sich eine annotierte Quelle ändert`isolating` — Gradle führt ihn einmal pro annotierter Quelle aus und fasst die Ergebnisse dann zusammen`dynamic` — der Processor wird nur ausgeführt, wenn er explizit über die CLI aufgerufen wird`incremental` — Gradle vergleicht die Ausgabe und gibt nur Änderungen aus