Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / Java

Adnotacje w Javie: cele, retencja, powtarzanie i refleksja

W Java SE 21 deklaracja adnotacji określa jej dane, dozwolone miejsca użycia i dostępność w czasie wykonania. Zobacz, jak odczytywać metadane przez refleksję, odróżniać odczyt lokalny od dziedziczenia i ograniczać zakres wyciszania ostrzeżeń.

Wersja: Java SE 21

Składnia

@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 deklaruje interfejs adnotacji. String value(); definiuje element, a @Tag("core") to skrót od @Tag(value = "core"). Metaadnotacja Target z java.lang.annotation określa dozwolone miejsca użycia. Zapis @Target(ElementType.TYPE/FIELD/CONSTRUCTOR) jest skrótem opisowym, nie składnią Javy: użyj @Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR}). ElementType.TYPE oznacza deklaracje klas i interfejsów, nie użycia typów (TYPE_USE). ElementType.FIELD/METHOD oznacza dwie stałe: ElementType.FIELD dla pól i ElementType.METHOD dla metod; konstruktory mają osobny cel.

Retention określa czas przechowywania: SOURCE nie trafia do pliku klasy, domyślne CLASS trafia do pliku, ale nie jest dostępne przez refleksję w czasie wykonania, a @Retention(RetentionPolicy.RUNTIME) udostępnia adnotacje z przykładu przez refleksję. Deklaracje zmiennych lokalnych i parametrów lambd stanowią wyjątek: ich adnotacje deklaracji nie trafiają do pliku klasy. Literał klasowy Base.class daje obiekt Class<Base>; Class<?> przyjmuje go bez ujawniania konkretnego argumentu typu. ConfigKey, Init, Component i Inject to własne metadane; bez kodu, który je interpretuje, niczego nie konfigurują, nie uruchamiają ani nie wstrzykują.

@Repeatable(Tags.class) pozwala wielokrotnie użyć @Tag w tym samym miejscu. Kompilator umieszcza powtórzenia w kontenerze z elementem Tag[] value(); pozostałe elementy kontenera muszą mieć wartości domyślne. Kontener musi mieć co najmniej tak długą retencję i zgodne cele; w przykładzie cele są identyczne. Jeśli Tag ma @Inherited, kontener także musi je mieć. getAnnotationsByType(Tag.class) rozwija kontener i dzięki Inherited szuka w nadklasach, gdy klasa nie ma własnych tagów. Nie łączy tagów z różnych poziomów, nie przeszukuje interfejsów i nie dziedziczy adnotacji metod ani pól. getDeclaredAnnotationsByType też rozwija kontener, ale nie szuka w nadklasach; getAnnotation nie rozwija kontenera.

new Consumer<Number>() { ... } deklaruje i tworzy obiekt klasy anonimowej. @Override pozwala kompilatorowi sprawdzić, czy accept(Number) implementuje metodę interfejsu, a nie jest przypadkowym przeciążeniem. Java 21 dopuszcza również sygnatury równoważne pod względem przesłaniania publicznym metodom Object oraz jawne akcesory komponentów rekordów.

Consumer<? super Integer> przyjmuje konsumenta Integer lub jego nadtypu, np. Number albo Object, i pozwala przekazać mu Integer. Symbol wieloznaczny bez ograniczenia ?, np. w Consumer<?>, oznacza nieznany argument typu i nie pozwala przekazać wartości Integer różnej od null. @SuppressWarnings("unchecked") wycisza ostrzeżenie kompilatora, ale nie sprawdza typów elementów listy ani nie zapobiega ClassCastException. Unikaj zbędnych rzutowań; jeśli rzutowanie jest uzasadnione, wycisz ostrzeżenie w najmniejszej skutecznej deklaracji.

Przykłady

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));
    }
}

Wynik

Config: port
Started: false -> true
Component/Inject: true/true
Tags: core, fast; declared: 0
Subscriber: 21
Cast: ok

`started` zmienia się dopiero po jawnym wywołaniu `method.invoke(service)`. `Child` odczytuje dwa tagi z `Base`, choć sam nie deklaruje żadnego. Rzutowanie jest tu uzasadnione znanym pochodzeniem listy z `List.of("ok")`, a nie obecnością `@SuppressWarnings`.

Powiązane lekcje

  • Java · Lekcja 44 · Zaawansowany · Wersja: 2
  • Java · Lekcja 54 · Zaawansowany · Wersja: 2
  • Java · Lekcja 58 · Zaawansowany · Wersja: 2
  • Java · Lekcja 59 · Zaawansowany · Wersja: 2

Źródła