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.