Toulouse JUG Presentation of the JSR 269 / Pluggable Annotation Processing API

1. PLUGGABLE ANNOTATION
PROCESSING API
JUG TOULOUSE - 2015 - LTE CONSULTING

2. ARNAUD TOURNIER
ArchiDév passionné chez LTE Consulting
Speaker Devoxx, GWT.create, Paris/Toulouse JUG, etc...
@ltearno www.lteconsulting.fr
Développement - Formation - Conseil
Full stack (x86_64 to JavaScript) !

3. AVANT TOUT
Cette présentation est disponible sur
github.com/ltearno/annotation-processing
Des hyper-liens sont présents

4. JSR 269 ???

5. PLUGGABLE ANNOTATION
PROCESSING API...

6. La JSR 269 - Pluggable Annotation Processing API permet
d'exploiter les annotations présentes dans le code en
s'insérant dans le processus de compilation, et de générer de
nouvelles sources.
Traitement des annotations à la compilation,
Génération de code,
Génération de fichiers de configuration,
Documentation, Cartographie,
Vérifications, Build breakers,
etc...
On ne modifie pas les sources existants !

7. AVANTAGES

8. Le code généré est visible.
Pas de traitement au runtime donc pas d'impact sur les
performances.
Pas d'instrumentation du byte-code, donc plus simple.

9. BRÈVE HISTOIRE DU
TRAITEMENT DES
ANNOTATIONS

10. COMMENTAIRES JAVADOC
XDoclet (2002)

11. APT
, retiré officiellement avec Java 7
car .
Annotation Processing Tool
non extensible à Java > 5
Outil lancé en dehors de la compilation.
L'API Mirror utilise les packages .

12. PLUGGABLE ANNOTATION PROCESSING API
Depuis 2006 (Java 6) la , créé par Joe Darcy.JSR-269
Intégré à la compilation .

13. PRINCIPE

14. On fournit un processeur d'annotation,
Le compilateur gère des de processing,
A chaque round, les nouveaux sources sont traités (phases
Parse et Enter),
Les processeurs sont choisis et reçoivent l'AST des classes
traitées,
Les processeurs peuvent générer de nouveaux fichiers
(sources, classes et resources) qui seront parsés et traités au
suivant.

15. UTILISATION

16. CRÉATION DE L'ANNOTATION

17. LE PROCESSEUR

18. LE FICHIER SPI
Pour packager et activer un processeur, le plus simple est
d'utiliser SPI :
Le fichier
contient la liste des processeurs :
Packager le tout dans un jar

19. UN BOUT DE CODE
Dans un autre projet on peut utiliser l'annotation et le
processeur.

20. PACKAGING ET COMPILATION
Le processeur et le fichier SPI sont dans un jar.
Ce jar est dans le class path au moment de la compilation de
.
C'est tout !

21. SORTIE DE NOTRE EXEMPLE

22. FONCTIONNEMENT

23. A chaque round, le processeur doit traiter les classes
générées au round précédent.
S'il est appelé au premier round, il le sera pour les autres,
jusqu'au dernier round (même si aucune annotation n'est
présente pour lui).

24. DÉCOUVERTE DES PROCESSEURS
Les proceseurs sont découverts par le compilateur.
fournit des options pour contrôler l'ensemble
des processeurs disponibles :
une liste prédéfinie,
un chemin de recherche,
utiliser SPI.

25. CHOIX DU PROCESSEUR
Appel des processeurs en fonction :
des annotations présentes dans les classes traitées,
les annotations supportées par les processeurs,
le fait qu'un processeur ait claimé une annotation.

26. CYCLE DE VIE DU PROCESSEUR
Le compilateur instancie le processeur,
Appelle avec un ,
Appelle ,
et
,
Et appelle à chaque round.

27. A CHAQUE ROUND
calcule l'ensemble des annotations sur les classes en
cours,
si au moins une annotation est présente, au fur et à mesure
que les processeurs les claime, elles sont retirées des
annotations non matchées.
quand l'ensemble est vide ou qu'il n'y a plus de processeur
candidat, le round est fini.
si aucune annotation n'est présente, seuls les processeurs
universels ("*") sont appelés, et reçoivent un ensemble vide
de classes à traiter.

28. PRÉCAUTIONS !
Un processeur ne doit pas dépendre d'un autre,
Idempotent,
Commutatif.

29. L'INTERFACE PROCESSOR

30. PROCESSINGENVIRONMENT

31. GETSUPPORTEDANNOTATIONTYPES

32. LA MÉTHODE PROCESS
On reçoit l'ensemble des annotations à traiter,
On retourne pour claimer les annotations et
empêcher les autres processeurs de les traiter.

33. ROUNDENVIRONMENT
Liste des classes dans le round :
Liste des éléments annotés :
Etat du round :

34. ELEMENT
javax.lang.model.element.Element
Représente un package, une classe, une méthode, ...
Pour parcourir les données d'un élément, il faut soit appeler
soit utiliser un visiteur.
Ne pas utiliser instanceof !
Petit exercice : POURQUOI ?

35. ELEMENT

36. LES SORTES D'ELEMENT
annotation, class, constructeur, enum, une constante enum,
parametre d'exception, champ, initializeur d'instance, interface,
variable locale, méthode, package, paramètre, variable de
resource, initializeur statique, paramètre de type, autres (futur).

37. LE FILER

38. CRÉER UN NOUVEAU SOURCE JAVA

39. CRÉER UNE NOUVELLE RESSOURCE

40. CRÉER UN NOUVEAU FICHIER .CLASS

41. UTILISATION DE TEMPLATES !
Ne générer que le minimum de code !
Velocity, ...
Java Poet, ...

42. LE MESSAGER

43. LE MESSAGER DANS ECLIPSE
La même erreur dans Eclipse

44. LA COMPILATION JAVA

45. 3 PHASES
Plan d'exécution de javac
Parse et Enter
Annotation Processing
Analyse et Generate
openjdk.java.net/groups/compiler/doc/compilation-overview

46. JAVAC
Action Paramètres
Génération
des sources
-s répertoire
Désigner un
processeur
-processor
fr.lteconsulting.MyAnnotationProcessor,autre...
Spécifier un
chemin de
recherche
-processorPath le_chemin
Passer des
options
-Acle=valeur

47. JAVAC (SUITE)
Action Paramètres
Désactiver l'AP -proc:none
Seulement l'AP -proc:only
Chemin de recherche des
sources
-sourcePath
Désactiver la génération des
implicite
-implicit:none
Répertoire de sortie des -d
Affichage debug -XprintRounds -
XprintProcessorInfo

48. ATTENTION : le warning si on ne met pas
docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.h

49. INTÉGRATION AVEC
ECLIPSE

50. CONFIGURATION
Eclipse utilise son propre compilateur, JDT.
Configuration possible du projet par m2e

52. ATTENTION
Dans Eclipse, si le projet contenant le processeur est ouvert,
l'annotation processing est désactivé.

53. TESTS UNITAIRES

54. EXEMPLE

55. COMPILE-TESTING
Bibliothèque de test développée par Google, pour aider le
développement de etAuto Dagger

56. Test positif

57. et négatif

58. DÉMO TIME !

59. LIMITATIONS

60. Pas d'accès à l'AST complet (corps des méthodes)
Pas possible de modifier des classes existantes
Certains bug ne permettent pas de traiter correctement les
génériques
Java et les IDE ne surveillent que les éléments annotés
pour redéclencher le processing (parfois problématique
lorsque l'on a des dépendances complexes -> !)

61. HACKING AU DELÀ
: de bons hacks pour accéder à l'implémentation
(javac de sun et jdt) et modifier l'AST
Immutables : quelques workarounds captant les
implementations JDK / JDT pour gérer les génériques
Explications techniques générales dans
Lombok
The Hacker's guide
to JavaC

62. EXEMPLES DE
BIBLIOTHÈQUES

63. JPA meta-model generation (JSR-317),
Dagger,
Google Auto,
Immutables,
Hexa Binding,
Lombok,
GWT (RequestFactory)

64. LIENS EN VRAC

65. , , ,
, , , ,
, ,
, ,
, ,
, ,
Hibernate Validation JM Doudoux Lombok How Lombok
works ? Lombok encore... Hacking JavaC HexaBinding
Coders Breakfast Prez d'Angelika Langer Dr. Macphail's
trance Créez et utilisz vos annotations Histoire des
annotation processing 4 vidéos sur Parleys Utilisation de la
JSR-269 chez Les Furets Save method parameter names Au
JUG Paris par Olivier Croisier...

66. ET VOILÀ !

67. MERCI !
Rendez-vous sur
github.com/ltearno/annotation-processing
Twitter :
LinkedIn : fr.linkedin.com/in/lteconsulting
LTE Consulting