Slides for my presentation given during the GWTCon 2015 conference in Firenze about generating (boiler plate) code with the JSR 269 inside a GWT Project. This JSR can of course also be used in pure Java projects.

1. PLUGGABLE ANNOTATION
PROCESSING API
GWT CON - 2015 - LTE CONSULTING

2. ARNAUD TOURNIER
Passionnate developper, trainer and architect at LTE
Consulting.
Speaker at Devoxx, GWT.create, Paris/Toulouse JUG, etc...
Email : ltearno@gmail.com
Twitter : @ltearno
Website : www.lteconsulting.fr
Full stack (x86_64 to JavaScript)

3. PRESENTATION AVAILABLE ON
lteconsulting.fr/annotation-processing
And the demo project is available at
github.com/ltearno/gwtcon-jsr269

4. GWT 3 WILL DROP GENERATORS !

5. JSR 269 TO THE
RESCUE???

6. PLUGGABLE ANNOTATION PROCESSING API
Code generation in Java (source, byte-code and resource).
Integrated with the Java compiler.
Based on annotations. The developer's annotation processor
receives most of the program's AST.

7. USED FOR ?
RPC stubs,
Reflection stubs,
UI generation,
Configuration file generation,
Code checkers, Build breakers,
Dependency injection,
Glue code generation,
Your own needs !

8. IN THE GWT CONTEXT
GWT 3 will abandon generators because the functionality
exists in standard Java : JSR 269.
Even with GWT 2.8 it makes sense to use it.
Causes migration problems, with most of the time quick
resolution.

9. GOOD POINTS
API is easy to use.
Generated code is visible and debuggable,
Generated code is known before compilation so you can
reference it directly (no GWT.create).
No overhead at runtime.
Does not depend on byte code : GWT compatible

10. BAD POINTS
Only annotated elements trigger processing. API makes it
difficult to coordinate processing of multiple classes over
multiple rounds (bad for incremental compilation).
Dependency to external resource is not managed either.

11. A BRIEF HISTORY

12. JAVADOC COMMENTS
XDoclet (2002)

13. APT
Introduced in JDK 5, was
removed with Java 7 because it support new language
elements.
Annotation Processing Tool
can't
Runs outside of .
API includes packages.

14. PLUGGABLE ANNOTATION PROCESSING API
Fixes the sins of the past.
has been included since Java 6 (2006).JSR-269
Runs inside of .
API is able to welcome new language features.

15. HOW IT WORKS
Annotation processors must be registered.
Java source files are compiled during rounds.
Each round, processors are activated and receive the
program's AST.
They can then generate files which will be part of the next
round.
When no file is generated during a round, real compilation
happens.

16. A SAMPLE

17. Let's say we want to develop a tool that automatically
generates UIs from any POJO...

18. DEMO'S PLAN

19. WE WILL HAVE TO
Write an annotation,
Write an annotation processor,
Register our processor through SPI,
Package and use our library.

20. ANNOTATION CREATION
This is the annotation we use to trigger the custom
annotation processing :

21. ANNOTATION PROCESSOR IMPLEMENTATION

22. REGISTERING THROUGH SPI
Java compiler searches annotation processors through SPI.
Add a file named META-
INF/services/javax.annotation.processing.Processor containing
the annotation processors' fqn list :
Other ways to register : has special flags. The
also has methods to set the processors to be
used.

23. PACKAGING
The simplest way is to have the annotation and its processor
in the same package.
Maven tip: dont forget to use the<compilerArgument>-
proc:none</compilerArgument> options

24. USING THE PROCESSOR
In a project with the processor's jar in the classpath, we can
use the annotation...
Eclipse tips :
Eclipse uses its own java compiler, JDT. Use m2e-apt to
configure your project if you work with maven.
Don't forget to close the processor project to have it activated.

25. THE POJO CLASS

26. THE GENERATED CLASS

27. USING THE GENERATED CLASS

28. HOW IS IT POSSIBLE ?
Using the not yet generated file is possible because the java
compiler deffers processing of the
NotFoundSymbolException.
The error is raised at the end of the parsing and annotation
processing process if the symbol has not been generated.

29. THE API : A BRIEF
INTRODUCTION

30. API OVERVIEW
Filer class : generate files (source, byte-code, resource)
Language Model classes : browse the program's structure,
Messager class : to communicate with the user,
Other tools : element and type tools
see javadoc of the javax.annotation.processing and
javax.lang.model packages.

31. API : JAVA SOURCE REPRESENTATION
Element : representation of a language construct (class
declarations, methods, ...). Ex: , ...
Supports all the language structures through the
and methods.
Hierarchical structure : ,
.
TypeMirror : Type representation, almost like Class<?>

32. API : ACCESSING ELEMENTS
Elements are given as parameters in the
method of the generator. Annotated elements are retrieved
like this :
.
All the classes parsed during the current round can be
obtained with :
.
Elements can also be retrieved with the utility methods :
,
and .

33. API : FILER
Creating a new Java source

34. API : MESSAGER
Outputs messages to the user.
Can also generate errors and break the build. Very handy to
assert things on the code.
IDE integration : hints on the API for the user.

35. API : TOOLS
Many tools can be retrieved from the
field of the
Other static methods and classes are helpful :

36. UNIT TESTS

37. TESTING A COMPILATION

38. COMPILE-TESTING
github.com/google/compile-testing
Annotation Processor testing library developped by Google
to help developping of the and projects.Auto Dagger

39. POSITIVE TESTS

40. AND NEGATIVE ONES

41. MISCELLANOUS

42. LIMITATIONS
Not a full access to the code's AST (instructions).
Processors cannot depend one on the other.
Incremental compilation is difficult when having
dependencies to more than one element or to external files.
on Eclipse : , on maven : have to disable incremental
compilation.
Most of the time those limitations are not embarassing.

43. HACKING
: based on JSR 269 and hacking both javac and jdt
in order to acces to internal implementations and mutate
the class AST.
Technical explanations in
Lombok
The Hacker's guide to JavaC

44. NOTE ON USING TEMPLATES
Try to generate the minimal amount of code, and base it on
generic implementations. This will ease debugging.
Tools :
Velocity, ...
Java Poet, ...
String.replaceAll()

45. LIBRARIES KNOWN USING JSR-269
JPA meta-model generation (JSR-317),
Dagger,
Google Auto,
Immutables,
Lombok,
GWT (RequestFactory),
Hexa Binding...

46. LINKS
,
, , , ,
, , ,
, ,
,
javadoc for annotation processing javadoc for Java Language
Model Hibernate Validation Lombok How Lombok works ?
Lombok again... Hacking JavaC Coders Breakfast Angelika
Langer presentation Dr. Macphail's trance Annotation
processing history Save method parameter names

47. THAT'S ALL, THANKS !

48. SEE YOU !
Slides : lteconsulting.fr/annotation-processing
Demo project : github.com/ltearno/gwtcon-jsr269
Twitter :
LTE Consulting : lteconsulting.fr
LinkedIn : fr.linkedin.com/in/lteconsulting