fbiville / annotation-processing-ftw Goto Github PK

Nous avons 3h au total.

Voici une proposition de déroulement :

10 min : annonce pré-requis + intro AP + explication atelier
15 min : check des pré-requis

5 min : explication exo 1
25 min : exo 1

5 min : présentation API javax.lang.model
20 min : exo 2

5 min : options du compilateur
20 min : exo 3

5 min : présentation de JavaPoet
25 min : exo 4

5 min : generics & class instance
40 minutes restantes : exo 5 (+ bonus pour les rapides)

WDYT @lesaint ?

les exercices sont tous en 0.5 alors que la 0.6 est dispo depuis octobre 2014 (my bad)

aucune fonctionnalité ajoutée dans la 0.6 dont on a besoin mais pour le principe, autant utiliser la dernière version (bien que la 0.6 ne soit pas - encore, PR en cours - indiquée comme la dernière version du projet dans le README)

talk

avec un AP, on peut générer des sources, des fichiers

• présentation de l'API Writer
• on peut le faire à la main, via un moteur de template ou via JavaPoet (présentation)
• parenthèse sur Lombok: on ne peut pas modifier les sources

exercices

• exo 1 : générer un fichier qui liste une certaine info extraite d'une certaine annotation
• exo 2 : générer une interface/classe au contenu fixe
  • quelle classe ? idée à trouver
  • sujet à trouver
• exo 3 : où sont générés les fichiers (pas au même endroit si ressource ou source) ? comment sont-ils gérés si on ne fait pas un clean (ils sont réécrits à chaque fois)
• exo 4 : générer une interface/classe dont le contenu dépend de la classe annotée
  • peu être l'un des exercices les plus longs
• exo 5 (bonus) : génération de classes en plusieurs rounds
  • sujet à trouver (générer class B à partir de class A, class C à partir de class B, etc.)
  • note de l'exo : indiquer que le @generated commen une bonne pratique
  • j'aimerai bien trouver un moyen de placer le flag isProcessingOver, mais pour l'instant je ne vois pas...

Suite à la remarque de @fbiville sur twitter, le niveau 2 requérant une bonne connaissance des streams pour être facile à écrire, les participants les moins expérimentés sur les streams seront probablement contents de trouver un peu de doc à ce sujet.

Hello, je propose plusieurs choses :

• on se met d'accord sur le périmètre des exercices (pas le contenu précis)
• on se les assigne ensuite entre nous
• une fois un exo terminé (i.e. section README + code à compléter + tests U), outre les discussions habituelles, le reviewer doit faire l'exo avant de valider la PR

@lesaint ça te va ?

Penser à "préalimenter" le repo Maven en passant une commande mvn dependency:go-offline (cf. http://maven.apache.org/plugins/maven-dependency-plugin/go-offline-mojo.html) sur tous et chacun des projets

Ne pas oublier le chargement de AutoService, JavaPoet & co

Il faut envisager le pire cas : les gens arrivent les mains dans les poches (avec 1 PC pour deux qd même) et le réseau est merdique.

Dans ce cas, que penses-tu de :

• d'1 image Docker contient déjà le bon JDK, Git, Maven & un repo Maven local minimum pour bosser
• d'emmener sur clef les binaires Docker et l'image en question

WDYT @lesaint ?

talk

pas de talk, si déjà certains participants arrivent à ce niveau là durant la session, il y aura probablement trop de monde à des endroits différents du hands-on pour avoir l'attention de la salle

exercices

• exo 1 : passer des options au processor
  • sujet possible : forker l'exo 1 du niveau 3 (erreur de compilation si un champs est annoté avec @Inject) pour qu'en fonction d'une option, on lève une erreur de compilation ou seulement des warnings
  • il serait intéressant de faire comme au niveau 1, avec d'abord une étape pour voir les options javac en ligne de commande, puis trouver comment passer les options dans maven (via le pom.xml et via la ligne de commande)
• exo 2 : exercice sur les intéractions entre les AP
• exo 3 : retourner "*" comme valeur de getSupportedAnnotationTypes
• ...

Talk

Introduction de l'Annotation Processing

• rapide historique
• la class Processor, le minimum à implémenter
• comment javac "trouve" le processor (déclaration manuelle vs service)
• le cycle de vie, intégration au process de compilation et notion de round
• rapide tour d'horizon des méthodes de la class Processor, des classes Writer et Messager

Exercices

Hello world et comment exécuter un AP

• exo 1: Hello world, exécution à la main (déclaration explicite et en ligne de commande)
• exo 2: Hello world, exécution automatique (autodiscovery et en ligne de commande)
• exo 3: activer les logs
• exo 4: la même chose avec Maven
• exo 5: se simplifier la vie avec @autoservice
  • Hey! "Inception" appliqué aux AP ! on fait de l'annotation processing à la compilation d'un annotation processor! :-)

Je propose qu'on fasse 1 exo = 1 PR.
1 PR sera toujours composée de 3 commits :

1. README complété
2. exo à trou + test(s) U
3. solution

On ne merge jamais, on rebase tout le temps.

Le premier commit sera ensuite fixup-é pour n'avoir qu'un commit initial unique de README.
Il restera ensuite à tagger tous les commits qui introduisent les nouveaux exos (voire aussi un tag pour les solutions).

@lesaint : WDYT?

la dernière version de Maven sortie est la 3.3.1 http://maven.apache.org/docs/3.3.1/release-notes.html

les participants risquent fortement d'avoir cette version installée, il est préférable de tester nos exercices avec cette version pour ne pas avoir de surprise

talk

Avec un AP, on peut étendre le compilateur => faire de la validation

• présentation de l'API Writer
• comment utiliser Processor#getSupportedAnnotationTypes()
• présentation de javax.lang.model.element.* et javax.lang.model.type.*
  • qu'est-ce qu'un Element ? qu'est-ce qu'un type ?
• utilisation des visiteurs pour connaître les types réels
• les exos de validation sont l'occasion d'utiliser compile-testing => le présenter rapidement

exercices

• exo 1 : validation d'annotations, erreur de compilation déplacé du niveau 3
  • sujet : empêcher @Inject sur les propriétés
  • apprendre en récupérer les annotations "surveillées"
  • 1er contact avec l'API Element/Type + utilisation de Messager
• exo 2 : et si vous affichiez la ligne à laquelle se trouve l'erreur ? déplacé au niveau 3
  • les paramètres des méthodes de Messager plus en détail
• exo 3 : et si vous n'affichiez qu'un warning ? déplacé du niveau 3
  • que se passe-t-il ? (rien sous Maven -- je crois)
• exo 4 : valider qu'une valeur d'un paramètre d'une annotation est unique par package
  • mise en avant de l'aspect statefull de l'AP et de son cycle de vie déjà couvert par la solution bourrin pour traiter le bégaiement du processor au niveau 1
• exo 5 à Z : connaître l'API javax.lang.model
  • série de tests unitaires dont le code d'exploration de l'API est à écrire
  • sujets multiples, mais il s'agit de découvrir les visiteurs, les classes Elements, Types, ElementFilters, les visiteurs et comment les utiliser
  • le sujet étant vaste, certains exercices pourront être relégué au dernier niveau, pour les plus rapides et pour éviter que ce niveau ne dure trop longtemps

Dans les README des exercices, il y a des TODO: lien doc qui doivent être remplacé par des liens vers la documentation et des solution: qui doivent être "cachés" dans une branche ou dans un fichier spécifique

Cette issue a pour objectif de lister les ressources à fournir en offline qui pourront être utiles aux participants. Pour constituer la liste, il suffit de penser à ce qu'on utilise ou a utilisé pour faire de l'AP nous même.

• javadoc JSR-269
• javadoc javax.lang.model part of JSR-269
• Java Language Specification (parce que quand on traite le modèle du langage Java, forcément, à un moment on a besoin de la spec)
  • HTML http://docs.oracle.com/javase/specs/jls/se8/html/index.html
  • PDF http://docs.oracle.com/javase/specs/jls/se8/jls8.pdf
  • PDF avec diff Java 7 http://docs.oracle.com/javase/specs/jls/se8/jls8-diffs.pdf
• la doc javac
  • http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html
• la doc ServiceLoader pour comprendre comment fonctionne l'auto discovery
  • http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html
• maven-compiler-plugin
• sources javac open-JDK (pour aller voir le source de classes comme JavacElements
• clone de @Auto (pour la doc de @AutoValue)
• clone de compilte-testing (contient la javadoc qui est la documentation du projet)
• clone de JavaPoet (la doc est dans le README.md)
• articles sur le sujet:
  • articles sur javatronic existants
  • articles sur javatronic que je dois finir d'écrire
  • introduction sur le sujet par Hannes Dorfmann
    • http://hannesdorfmann.com/annotation-processing/annotationprocessing101/