CKTIS / Java
Annotazioni Java: destinazioni, conservazione, ripetizione e riflessione
In Java SE 21, la dichiarazione di un’annotazione stabilisce quali dati contiene, dove può comparire e se è visibile a runtime. Impara a leggere i metadati tramite riflessione, a riconoscere le annotazioni ereditate e a limitare la soppressione degli avvisi.
Versione: Java SE 21
Sintassi
@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 dichiara un’interfaccia di annotazione. String value(); definisce un elemento e @Tag("core") abbrevia @Tag(value = "core"). La meta-annotazione Target di java.lang.annotation stabilisce dove può comparire l’annotazione. @Target(ElementType.TYPE/FIELD/CONSTRUCTOR) è una scorciatoia descrittiva, non sintassi Java: scrivi @Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR}). ElementType.TYPE riguarda le dichiarazioni di classi e interfacce, non gli usi di un tipo (TYPE_USE). ElementType.FIELD/METHOD indica due costanti: ElementType.FIELD per i campi e ElementType.METHOD per i metodi. I costruttori hanno una destinazione distinta.
Retention regola la conservazione: SOURCE non finisce nel file di classe, CLASS è il valore predefinito e viene registrato ma non è visibile tramite riflessione a runtime, mentre @Retention(RetentionPolicy.RUNTIME) rende disponibili tramite riflessione le annotazioni dell’esempio. Fanno eccezione le annotazioni sulle dichiarazioni di variabili locali e parametri di lambda, che non vengono salvate nel file di classe. Il letterale di classe Base.class restituisce un oggetto Class<Base>; Class<?> lo accetta senza esporre l’argomento di tipo specifico. ConfigKey, Init, Component e Inject sono metadati personalizzati: senza codice che li interpreti non configurano, invocano né iniettano nulla.
@Repeatable(Tags.class) permette di applicare più @Tag nello stesso punto. Il compilatore raggruppa le ripetizioni in un contenitore con Tag[] value(); gli altri elementi del contenitore devono avere valori predefiniti. Il contenitore deve avere una conservazione almeno altrettanto lunga e destinazioni compatibili; nell’esempio le destinazioni coincidono. Se Tag ha @Inherited, anche il contenitore deve averla. getAnnotationsByType(Tag.class) estrae le annotazioni dal contenitore e, grazie a Inherited, cerca nelle superclassi se la classe non ha tag propri. Non unisce tag di livelli diversi, non consulta le interfacce e non eredita annotazioni di metodi o campi. getDeclaredAnnotationsByType estrae anch’esso le annotazioni dal contenitore, ma non risale alle superclassi; getAnnotation non apre il contenitore.
new Consumer<Number>() { ... } dichiara e istanzia una classe anonima. @Override permette al compilatore di verificare che accept(Number) implementi il metodo dell’interfaccia invece di crearne per errore un overload. Java 21 ammette anche firme equivalenti ai fini dell’override a quelle di metodi pubblici di Object e metodi di accesso espliciti per componenti di record.
Consumer<? super Integer> accetta un consumer di Integer o di un suo supertipo, come Number o Object, e gli si può passare un Integer. Il jolly senza vincoli ?, come in Consumer<?>, lascia sconosciuto l’argomento di tipo e non consente di passare un Integer diverso da null. @SuppressWarnings("unchecked") silenzia l’avviso del compilatore, ma non verifica i tipi degli elementi della lista e non impedisce ClassCastException. Evita i cast inutili; se un cast è giustificato, sopprimi l’avviso nella dichiarazione più circoscritta in cui funziona.
Esempi
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));
}
}Risultato
Config: port Started: false -> true Component/Inject: true/true Tags: core, fast; declared: 0 Subscriber: 21 Cast: ok
`started` cambia solo quando viene chiamato esplicitamente `method.invoke(service)`. `Child` legge due tag da `Base` pur non dichiarandone nessuno. Il cast è giustificato dall’origine nota della lista, `List.of("ok")`, non da `@SuppressWarnings`.
Lezioni correlate
- Java · Lezione 44 · Avanzato · Versione: 2
- Java · Lezione 54 · Avanzato · Versione: 2
- Java · Lezione 58 · Avanzato · Versione: 2
- Java · Lezione 59 · Avanzato · Versione: 2
Fonti
- 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