Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / Java

Typy adnotacji — @interface

Deklaracja @interface definiuje typ adnotacji, czyli metadanych dołączanych do kodu. Elementy określają dane adnotacji, a metaadnotacje sterują miejscami użycia, retencją, powtarzalnością i dziedziczeniem.

Wersja: Java SE 21; repository runtime, production runtime not attested

Składnia

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Label {
    String value();
    int priority() default 0;
}

@interface definiuje typ adnotacji. Element, np. String value();, jest bezparametrową metodą bez ciała. Dozwolone typy to typy proste, String, Class, enumy, typy adnotacji i ich jednowymiarowe tablice; wartością nie może być null. Element bez default jest wymagany. @Label("demo") skraca @Label(value = "demo"), gdy pozostałe elementy mają wartości domyślne.

@Retention określa trwałość metadanych: RetentionPolicy.SOURCE oznacza odrzucenie przez kompilator, RetentionPolicy.CLASS — zapis w pliku klasy bez gwarancji dostępności przez refleksję, a RetentionPolicy.RUNTIME — zachowanie także podczas wykonania. Możliwość odczytu przez refleksję zależy jednak od miejsca użycia adnotacji. Na przykład adnotacja użycia typu w wyrażeniu rzutowania z retencją RetentionPolicy.RUNTIME może zostać zapisana w pliku klasy, ale standardowy interfejs API refleksji w Java SE 21 jej nie udostępnia. Adnotacje dotyczące samych deklaracji zmiennych lokalnych lub parametrów wyrażeń lambda nie są zapisywane w pliku klasy, nawet przy RetentionPolicy.RUNTIME. Bez @Retention obowiązuje RetentionPolicy.CLASS. Sama adnotacja nie uruchamia logiki: musi ją interpretować narzędzie lub kod.

@Target ogranicza dozwolone miejsca użycia. ElementType.TYPE obejmuje deklaracje klas, interfejsów, enumów i rekordów; ElementType.FIELD — pola, w tym stałe enumów; ElementType.METHOD — metody; ElementType.CONSTRUCTOR — konstruktory. ElementType.TYPE nie oznacza dowolnego użycia typu: do tego służy ElementType.TYPE_USE.

@Repeatable wskazuje kontener umożliwiający powtórzenie tej samej adnotacji. Kontener deklaruje value() zwracające tablicę powtarzanego typu, a jego pozostałe elementy muszą mieć wartości domyślne. Musi też spełniać reguły zgodności retencji, celów i metaadnotacji określone w JLS.

@Inherited pozwala odpowiednim zapytaniom refleksji o adnotacje klasy przeszukiwać nadklasy. Nie przenosi adnotacji z implementowanych interfejsów ani nie powoduje dziedziczenia adnotacji metod, pól lub konstruktorów. Przykład pokazuje cztery dozwolone cele oraz odczyt wartości jawnej i domyślnej.

Przykłady

import java.lang.annotation.*;

public class Main {
    @Retention(RetentionPolicy.RUNTIME)
    @Target({ElementType.TYPE, ElementType.FIELD,
             ElementType.METHOD, ElementType.CONSTRUCTOR})
    public @interface Label {
        String value();
        int priority() default 0;
    }

    @Label("demo")
    static class Item {
        @Label("id")
        int id;

        @Label("create")
        Item() {}

        @Label(value = "read", priority = 2)
        void read() {}
    }

    public static void main(String[] args) throws ReflectiveOperationException {
        Label type = Item.class.getAnnotation(Label.class);
        Label method = Item.class.getDeclaredMethod("read").getAnnotation(Label.class);
        System.out.println(type.value() + ":" + type.priority());
        System.out.println(method.value() + ":" + method.priority());
    }
}

Wynik

demo:0
read:2

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła