Java Reflection: Lettura delle Annotazioni a Runtime

I capitoli precedenti hanno trattato la dichiarazione delle annotazioni (vedi Annotazioni Personalizzate e Meta-Annotazioni); questo capitolo riguarda la lettura delle annotazioni a runtime tramite la reflection. Un'annotazione con @Retention(RUNTIME) diventa interrogabile su Class, Method, Field, Constructor e Parameter a cui è associata. La lettura delle annotazioni è il modo in cui JUnit trova @Test, Spring trova @Autowired e i framework di validazione trovano @NotNull. Questo capitolo raccoglie in un unico posto l'intero API di lettura, incluse le particolarità di @Inherited e @Repeatable.

Questa pagina copre i quattro metodi di lettura di AnnotatedElement, perché la retention è un prerequisito fondamentale, come @Inherited e @Repeatable modificano ciò che si ottiene, come leggere le annotazioni dei parametri e un esempio funzionante di scanner di validazione che puoi eseguire.

I quattro metodi di lettura

Ogni elemento annotabile (Class, Method, Field, Constructor, Parameter) implementa AnnotatedElement, che definisce gli stessi quattro metodi ovunque:

AnnotatedElement el = SomeClass.class;   // or a Method, Field, etc.

el.isAnnotationPresent(Audited.class);   // boolean — quick check
el.getAnnotation(Audited.class);         // the annotation instance, or null
el.getAnnotations();                     // ALL annotations (declared + inherited)
el.getDeclaredAnnotations();             // only those declared directly here

Poiché l'API è uniforme, il codice per leggere un'annotazione da un metodo è identico a quello per leggerla da una classe — si tiene semplicemente un AnnotatedElement diverso. I valori delle annotazioni recuperati sono proxy generati dalla JVM; chiamare a.value() è una vera chiamata a metodo che restituisce il valore dell'elemento definito al momento della compilazione.

La retention è un prerequisito

Vale la pena ripeterlo perché è il bug numero uno: solo le annotazioni con retention RUNTIME sono visibili alla reflection.

@Retention(RetentionPolicy.RUNTIME)   // <-- required for reflection
@interface Audited { String value(); }

La retention predefinita è CLASS, che mantiene l'annotazione nel file .class ma la elimina prima del runtime. La retention SOURCE la elimina ancora prima. Se getAnnotation restituisce null su un'annotazione che puoi vedere chiaramente nel sorgente, la mancanza di @Retention(RUNTIME) è quasi sempre la causa.

`getAnnotations` vs `getDeclaredAnnotations` e `@Inherited`

La differenza tra questi due è @Inherited. Per impostazione predefinita le annotazioni non vengono ereditate dalle sottoclassi. Ma se un tipo di annotazione è esso stesso meta-annotato con @Inherited, allora una sottoclasse eredita un'annotazione a livello di classe dalla sua superclasse:

@Inherited
@Retention(RetentionPolicy.RUNTIME)
@interface Component { }

@Component class Base { }
class Derived extends Base { }     // Derived has no @Component in source

Derived.class.getAnnotation(Component.class)          // → present! (inherited)
Derived.class.getDeclaredAnnotation(Component.class)  // → null (not declared here)

Quindi getAnnotations() include le annotazioni ereditate; getDeclaredAnnotations() riporta solo ciò che è fisicamente scritto su quell'elemento. Due limiti importanti: @Inherited funziona solo per le annotazioni di classe (non per metodi o campi), e solo lungo la catena della superclasse (non delle interfacce).

Annotazioni ripetibili

Da Java 8, un'annotazione contrassegnata con @Repeatable può apparire più volte sullo stesso elemento. Internamente il compilatore raggruppa le ripetizioni in un'annotazione contenitore, quindi il semplice getAnnotation non le vedrà — si usa getAnnotationsByType, che spacchetta in modo trasparente il contenitore:

@Repeatable(Roles.class)
@Retention(RetentionPolicy.RUNTIME)
@interface Role { String value(); }
@Retention(RetentionPolicy.RUNTIME)
@interface Roles { Role[] value(); }     // the container

@Role("admin") @Role("user") class Account { }

Account.class.getAnnotationsByType(Role.class);   // → [Role(admin), Role(user)]
Account.class.getAnnotation(Role.class);          // → null! (it's wrapped in Roles)

Usa getAnnotationsByType(Role.class) per le annotazioni ripetibili; restituisce un array e gestisce sia il caso singolo che quello ripetuto.

Lettura delle annotazioni di parametri e altri target

I parametri ricevono le proprie annotazioni tramite l'array bidimensionale Method.getParameterAnnotations() (un array per parametro), oppure tramite l'API più chiara di Parameter:

for (Parameter p : method.getParameters()) {
  if (p.isAnnotationPresent(NotNull.class)) { /* validate */ }
}

Gli stessi metodi di AnnotatedElement funzionano su Field, Constructor, Package, e persino sulle annotazioni stesse (per leggere le meta-annotazioni come @Retention). Per come ottenere gli handle di Method, Field e Constructor, vedi Reflecting Methods, Fields e Constructors.

Nota

getParameterAnnotations() restituisce un array [parameterIndex][annotation] — un array interno per ogni parametro, anche per i parametri senza annotazioni (quegli array interni sono semplicemente vuoti). Il ciclo basato su Parameter sopra è di solito più chiaro.

Un esempio pratico: un mini scanner di validazione

Il programma dichiara annotazioni a runtime, contrassegna i casi @Inherited e @Repeatable, e poi uno scanner generico percorre le annotazioni di una classe, le annotazioni dei suoi metodi e le annotazioni dei parametri dei suoi metodi — lo scheletro di un framework di validazione o routing.

java— editable, runs on the server

import java.lang.annotation.*;
import java.lang.reflect.*;

public class ReflectionAnnotationsDemo {

@Inherited
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.TYPE)
  @interface Service { String value() default ""; }

@Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.METHOD)
  @interface Endpoint { String path(); }

@Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.PARAMETER)
  @interface NotNull { }

@Repeatable(Roles.class)
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.METHOD)
  @interface Role { String value(); }
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.METHOD)
  @interface Roles { Role[] value(); }

@Service("users")
  static class UserController {
    @Endpoint(path = "/users")
    @Role("admin") @Role("auditor")
    public String list(@NotNull String tenant, int page) {
      return "listing " + tenant + " page " + page;
    }
  }

// UserController is @Service; this subclass inherits it (annotation is @Inherited)
  static class AdminController extends UserController { }

public static void main(String[] args) throws Exception {
    Class<?> c = UserController.class;

// class-level annotation
    Service svc = c.getAnnotation(Service.class);
    System.out.println("@Service value = \"" + svc.value() + "\"");

// @Inherited: subclass sees the superclass annotation
    System.out.println("Admin inherits @Service? "
        + AdminController.class.isAnnotationPresent(Service.class));
    System.out.println("Admin DECLARES @Service? "
        + (AdminController.class.getDeclaredAnnotation(Service.class) != null));

// method-level + repeatable
    Method list = c.getDeclaredMethod("list", String.class, int.class);
    Endpoint ep = list.getAnnotation(Endpoint.class);
    System.out.println("\n@Endpoint path = " + ep.path());
    System.out.println("getAnnotation(Role) = " + list.getAnnotation(Role.class)); // null!
    Role[] roles = list.getAnnotationsByType(Role.class);
    System.out.print("roles via getAnnotationsByType = [");
    for (int i = 0; i < roles.length; i++)
      System.out.print(roles[i].value() + (i < roles.length - 1 ? ", " : ""));
    System.out.println("]");

// parameter annotations
    System.out.println("\nparameters:");
    for (Parameter p : list.getParameters()) {
      System.out.println("  " + p.getType().getSimpleName()
          + " @NotNull? " + p.isAnnotationPresent(NotNull.class));
    }

// a SOURCE/CLASS-retained annotation would be invisible here:
    System.out.println("\nall runtime annotations on list(): "
        + list.getDeclaredAnnotations().length + " (Endpoint + Roles container)");
  }
}

Cosa osservare dall'esecuzione:

getAnnotation(Service.class) ha restituito un proxy live il cui value() ha dato "users" — il valore scritto nel sorgente. Leggere un'annotazione significa semplicemente chiamare i metodi dei suoi elementi; il framework reagisce a quei valori (qui, trattando "users" come prefisso di route). L'annotazione porta dati, lo scanner fornisce il comportamento.
AdminController ha riportato @Service come presente ma non dichiarata: isAnnotationPresent ha restituito true (ereditata da UserController) mentre getDeclaredAnnotation ha restituito null. Questa differenza è interamente dovuta alla meta-annotazione @Inherited, e funziona solo perché @Service punta a una classe — i metodi e i campi non ereditano mai le annotazioni in questo modo.
list.getAnnotation(Role.class) ha restituito null anche se due annotazioni @Role sono chiaramente presenti nel sorgente. Le annotazioni ripetibili vengono raggruppate in un contenitore Roles dal compilatore, quindi il getter a valore singolo non le vede; getAnnotationsByType(Role.class) ha spacchettato il contenitore e restituito entrambi i ruoli. Usa sempre getAnnotationsByType per le annotazioni ripetibili.
Le annotazioni dei parametri erano accessibili per singolo parametro: il parametro tenant ha riportato @NotNull presente e page no. Questa granularità per parametro è ciò che i framework di bean-validation e request-binding usano per validare o iniettare i singoli argomenti.
getDeclaredAnnotations() su list ha contato due annotazioni — @Endpoint e il contenitore sintetico Roles — confermando che i due @Role si sono collassati in un unico contenitore a livello di class file. Qualsiasi annotazione priva di @Retention(RUNTIME) non sarebbe apparsa in quel conteggio.

Pratica

Un framework contrassegna i metodi con un'annotazione ripetibile '@Role' (un metodo può averne molte). Su un metodo annotato '@Role('admin') @Role('editor')', chiamare 'method.getAnnotation(Role.class)' restituisce null. Perché, e cosa si dovrebbe chiamare invece?

Le annotazioni ripetibili vengono raggruppate dal compilatore in un'annotazione contenitore, quindi 'getAnnotation(Role.class)' non trova nulla; usa 'getAnnotationsByType(Role.class)', che spacchetta il contenitore e restituisce tutte le istanze di 'Role'L'annotazione manca di '@Inherited', quindi 'getAnnotation' non può vederla; aggiungendo '@Inherited' si fa restituire la prima'getAnnotation' funziona solo per le annotazioni a livello di classe; per i metodi occorre chiamare 'getMethodAnnotation(Role.class)'Le annotazioni ripetibili vengono scartate a runtime indipendentemente dalla retention, quindi nessuna delle due chiamate può leggerle; bisogna analizzare il file sorgente