CKTIS / Java
Java-Annotationen: Ziele, Aufbewahrung, Wiederholung und Reflection
In Java SE 21 legt die Deklaration einer Annotation ihre Daten, ihre zulässigen Einsatzorte und ihre Sichtbarkeit zur Laufzeit fest. Lerne, Metadaten per Reflection zu lesen, wiederholte Annotationen zu erben und Warnungen gezielt zu unterdrücken.
Version: Java SE 21
Syntax
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR})
@interface Marker {}
@Target({ElementType.FIELD, ElementType.METHOD})
@interface MemberMarker {}
@Inherited
@Repeatable(Tags.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tag { String value(); }
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tags { Tag[] value(); }
Consumer<? super Integer> subscriber = new Consumer<Number>() {
@Override public void accept(Number value) { System.out.println(value); }
};
Class<?> type = String.class;
Object payload = List.of("ok");
@SuppressWarnings("unchecked")
List<String> names = (List<String>) payload;@interface deklariert eine Annotationsschnittstelle. String value(); definiert ein Element; @Tag("core") steht kurz für @Tag(value = "core"). Die Meta-Annotation Target aus java.lang.annotation legt die zulässigen Einsatzorte fest. @Target(ElementType.TYPE/FIELD/CONSTRUCTOR) ist eine beschreibende Kurzform, keine Java-Syntax. Schreibe @Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR}). ElementType.TYPE gilt für Klassen- und Schnittstellendeklarationen, nicht für die Verwendung eines Typs (TYPE_USE). ElementType.FIELD/METHOD bezeichnet zwei Konstanten: ElementType.FIELD für Felder und ElementType.METHOD für Methoden. Konstruktoren haben ein eigenes Ziel.
Retention bestimmt die Aufbewahrung: SOURCE gelangt nicht in die Klassendatei, der Standard CLASS wird gespeichert, ist aber zur Laufzeit nicht per Reflection verfügbar, und @Retention(RetentionPolicy.RUNTIME) macht die Annotationen des Beispiels per Reflection lesbar. Deklarationsannotationen lokaler Variablen und von Lambda-Parametern sind Ausnahmen: Sie werden nicht in der Klassendatei gespeichert. Das Klassenliteral Base.class ergibt ein Class<Base>-Objekt; Class<?> nimmt es auf, ohne das konkrete Typargument offenzulegen. ConfigKey, Init, Component und Inject sind selbst definierte Metadaten. Ohne auswertenden Code konfigurieren, starten oder injizieren sie nichts.
@Repeatable(Tags.class) erlaubt mehrere @Tag-Annotationen an derselben Stelle. Der Compiler bündelt sie in einem Container mit Tag[] value(); weitere Elemente brauchen Standardwerte. Der Container muss mindestens ebenso lange aufbewahrt werden und kompatible Ziele haben; im Beispiel sind die Ziele identisch. Hat Tag ein @Inherited, braucht es auch der Container. getAnnotationsByType(Tag.class) packt den Container aus und sucht dank Inherited in Oberklassen, wenn die Klasse keine eigenen Tags hat. Es führt keine Tags verschiedener Ebenen zusammen, durchsucht keine Schnittstellen und erbt keine Annotationen von Methoden oder Feldern. getDeclaredAnnotationsByType packt ebenfalls Container aus, durchsucht aber keine Oberklassen; getAnnotation packt keine Container aus.
new Consumer<Number>() { ... } deklariert und instanziiert eine anonyme Klasse. Mit @Override prüft der Compiler, dass accept(Number) die Schnittstellenmethode implementiert, statt sie versehentlich zu überladen. Java 21 erlaubt auch zum Überschreiben äquivalente Signaturen öffentlicher Object-Methoden und explizite Zugriffsmethoden für Record-Komponenten.
Consumer<? super Integer> akzeptiert einen Consumer für Integer oder einen seiner Obertypen wie Number oder Object; ihm kann man ein Integer übergeben. Beim unbeschränkten Platzhalter ?, etwa in Consumer<?>, ist das Typargument unbekannt: Ein von null verschiedenes Integer kann man nicht übergeben. @SuppressWarnings("unchecked") unterdrückt die Compilerwarnung, prüft aber keine Listenelementtypen und verhindert keine ClassCastException. Vermeide unnötige Casts; ist einer begründet, unterdrücke die Warnung an der kleinsten wirksamen Deklaration.
Beispiele
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.List;
import java.util.function.Consumer;
public class Demo {
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@interface ConfigKey { String value(); }
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@interface Init {}
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Component {}
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.CONSTRUCTOR})
@interface Inject {}
@Inherited
@Repeatable(Tags.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tag { String value(); }
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Tags { Tag[] value(); }
@Component
@Tag("core")
@Tag("fast")
static class Base {
@ConfigKey("port") final int port = 8080;
boolean started;
@Inject Base() {}
@Init void start() { started = true; }
}
static class Child extends Base {}
static void publish(Consumer<? super Integer> subscriber) {
subscriber.accept(21);
}
public static void main(String[] args) throws ReflectiveOperationException {
Class<?> type = Base.class;
Base service = new Base();
var field = type.getDeclaredField("port");
System.out.println("Config: " + field.getAnnotation(ConfigKey.class).value());
boolean before = service.started;
var method = type.getDeclaredMethod("start");
if (method.isAnnotationPresent(Init.class)) {
method.invoke(service);
}
System.out.println("Started: " + before + " -> " + service.started);
System.out.println("Component/Inject: " + type.isAnnotationPresent(Component.class)
+ "/" + type.getDeclaredConstructor().isAnnotationPresent(Inject.class));
Tag[] tags = Child.class.getAnnotationsByType(Tag.class);
int declared = Child.class.getDeclaredAnnotationsByType(Tag.class).length;
System.out.println("Tags: " + tags[0].value() + ", " + tags[1].value()
+ "; declared: " + declared);
publish(new Consumer<Number>() {
@Override public void accept(Number value) {
System.out.println("Subscriber: " + value);
}
});
Object payload = List.of("ok"); // This list is known here to contain only strings.
@SuppressWarnings("unchecked")
List<String> names = (List<String>) payload;
System.out.println("Cast: " + names.get(0));
}
}Ergebnis
Config: port Started: false -> true Component/Inject: true/true Tags: core, fast; declared: 0 Subscriber: 21 Cast: ok
`started` ändert sich erst beim expliziten Aufruf von `method.invoke(service)`. `Child` liest zwei Tags von `Base`, obwohl es selbst keine deklariert. Der Cast ist hier durch die bekannte Herkunft der Liste aus `List.of("ok")` begründet, nicht durch `@SuppressWarnings`.
Zugehörige Lektionen
- Java · Lektion 44 · Fortgeschritten · Version: 2
- Java · Lektion 54 · Fortgeschritten · Version: 2
- Java · Lektion 58 · Fortgeschritten · Version: 2
- Java · Lektion 59 · Fortgeschritten · Version: 2
Quellen
- Java SE 21 Language Specification §9.6 — Annotation Interfaces and Predefined Annotation Interfaces
- Java SE 21 Language Specification §9.7.5 — Multiple Annotations of the Same Interface
- Java SE 21 API — ElementType
- Java SE 21 API — RetentionPolicy
- Java SE 21 API — AnnotatedElement
- Java SE 21 API — SuppressWarnings
- Java SE 21 Language Specification §4.5.1 — Type Arguments of Parameterized Types
- Java SE 21 Language Specification §15.8.2 — Class Literals
- Java SE 21 Language Specification §15.9.5 — Anonymous Class Declarations