Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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