Processore di annotazioni in action

Generazione del codice

Sulla base di quanto esposto nei capitolo precedenti, una volta individuate tutte le classi decorate con l'annotazione @Convert è il momento di generare i relativi convertitori.

@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
  ...
  // analizza tutti gli elementi annotati con Factory
  for (Element item : roundEnv.getElementsAnnotatedWith(Convert.class)) {
    // Verifichiamo che siano di tipo class
    if (item.getKind() != ElementKind.CLASS) {
      error(item, "Solo le classi possono essere annotate con l'annotazione @%s", Convert.class.getSimpleName());
      return true;
    }
    TypeElement typeElement = (TypeElement) item;
    ConvertDefinition adapterDefinition = new ConvertDefinition(typeElement);
    ConvertGenerator.build(adapterDefinition, elements, filer);
  }
  ...
  return true;
}

Per la generazione del codice si possono usare diversi meccanismi, tra cui è possibile includere:

• concatenazione di stringhe: il codice usato per generare le classi è contenuto in stringhe che vengono concatenate tra loro a seconda di come si desidera generare il codice.
• template engine: un po' più sofisticato del primo caso, si basa sull'uso di template engine quali ad esempio Velocity.
• generatori di codice: il codice viene generato mediante una libreria preposta alla generazione di codice Java, come per esempio JavaPoet.

Nel nostro esempio useremo JavaPoet. Per ulteriori approfondimenti su tale libreria, si rimanda alla documentazione del progetto.

A prescindere dal meccanismo utilizzato per la generazione del codice, la scrittura del file avviene mediante il Writer fornito dal Filer che si era ottenuto nel metodo init() del processore.

Registrazione del processore

Il processore verrà utilizzato dal compilatore mediante il jar prodotto dal progetto "annotation-processor". Un processore, per poter essere utilizzato, deve essere collocato in un jar e registrato nel file denominato javax.annotation.processing.Processor posizionato sul percorso META-INF/services del jar stesso. La struttura del progetto "annotation-processor" può essere illustrata con l'immagine seguente

I processori presenti nel file Processor sono definiti uno per riga mediante il nome completo della classe che li implementa. Per il processore d'annotazione del nostro esempio il contenuto del file sarà:

it.html.jap.ConvertProcessor

Build dei progetti

Il processo di build dei progetti avviene nel modo standard con cui vengono eseguiti i progetti maven. Le operazioni da eseguire per tutti e tre i progetti si riassumono in clean install. Il progetto Example contiene un'unica classe di test nella quale viene usato il converter generato dall'annotazione. Riuscire ad eseguire senza errori tale test indica che la configurazione dei progetti e la generazione del converter sono andati a buon fine.

I progetti devono essere eseguiti nell'ordine: "annotation", "annotation-processor" ed "example". I file pom.xml dei progetti "annotation-process" e "annotation" non contengono nessuna particolarità. Il file pom.xml del progetto "example" è invece interessante in quanto:

• viene definita la dipendenza dal progetto del processore con scope compile: in questo modo il processore non verrà incluso nelle dipendenze a runtime dell'applicativo.
• Viene prdinato al compilatore mediante il tag processor di utilizzare il processore di annotazione che abbiamo definito per creare le factory.

Importando il progetto "example", Eclipse segnalerà la presenza di alcuni errori in quanto la factory non è stata ancora creata. Bisognerà quindi eseguire la build con maven per risolvere tale problema. Eseguendo la build del progetto "example", verrà creata dentro la cartella target il codice sorgente dei converter.

Bisogna includere tale cartella nel build path per consentire ad Eclipse di trovare le classi generate.

Conclusioni

Lo scopo di questa serie di articoli era illustrare come funzionano i processori di annotazioni presenti in Java. Al fine di rendere la spiegazione più semplice, si è scelto di realizzare un AP che consentisse di automatizzare la conversione di una classe Java in una classe di tipo ContentValues. Questo tipo di classe viene usata, su piattaforma Android, per inserire dati in tabelle di database SQLite. Si è visto quali sono i metodi principali che caratterizzano un AP e come essi vedono i file java che analizzano alla ricerca di annotazioni.

Troverete in allegato il codice usato in questa serie di articoli. Happy coding!