1. Copyright BEA 2005, made available under EPL 1.0 | 1 Using Java Annotations in Eclipse Gary Horen BEA Systems Tim Wagner BEA Systems

2. Copyright BEA 2005, made available under EPL 1.0. | 2 Agenda Background Simple Example Demo Mirror API and APT Pitfalls More Elaborate Example Futures

3. Copyright BEA 2005, made available under EPL 1.0. | 3 What are annotations? Metadata placed directly in your source code Standardized by JSR 175, added to Java in 1.5 Intended to replace “xdoclet”-style programming with a modern, type-checked equivalent @MyAnnotation(num=5, str=“hi”) public class Foo { … }

4. Copyright BEA 2005, made available under EPL 1.0. | 4 What are annotations? Defined using Java – much like interfaces Can be used by both tools and runtimes Enable a simpler “POJO”-based programming model public @interface MyAnnotation { int num; String str; }

5. Copyright BEA 2005, made available under EPL 1.0. | 5 What can an annotation do? @Webservice Public class Foo { } Endpoint Interface XML-Java Bindings Example: helping a POJO to become a web service Annotations on user code generate helper objects Endpoint interface: receives and parses XML message Bindings embody the message as parameters to the POJO method generates

6. Copyright BEA 2005, made available under EPL 1.0. | 6 Who uses annotations? J2SE – builtin annotations J2EE – EBJ 3.0, JSR 181, JSR 250, JAXB 2.0, JAX-WS 2.0 3 rd party frameworks: Hibernate, Beehive, Spring …and eventually every major IT organization @Deprecated @WebService @Persistent @MyCorporateAnnotation

7. Copyright BEA 2005, made available under EPL 1.0. | 7 Build-time uses Many annotations effects happen at build time, not run time “I need to create a stub/skeleton that matches this interface” “I need to inform my container that I need resource X” “I need to verify that this method meets some constraints” We need several things to make this useful Something to process a set of annotations – an annotation processor A build (compile) time container for these processors – a compiler with extra smarts Enhanced visual tools – make Eclipse aware of the special semantics of annotations

8. Copyright BEA 2005, made available under EPL 1.0. | 8 Process view Processor Container @MyAnno public class Foo {... } Annotated Source File apt tool in JDK 1.5 or Eclipse apt plugin compiles @MyAnno processoranother processor calls

9. Copyright BEA 2005, made available under EPL 1.0. | 9 What can an annotation processor do? Can Claim a set of annotations Check annotations for semantic errors Generate new Java source files Generate arbitrary data files (e.g. deployment descriptor) Cannot Change the bytecode generated when the file is compiled in any way

10. Copyright BEA 2005, made available under EPL 1.0. | 10 Demo DemoAnnotation An Annotation contains elements Elements contain names and values An annotation processor can check element values for correctness TypeGeneratingAnnotation Generates a Java source file

11. Copyright BEA 2005, made available under EPL 1.0. | 11 Demo: processor finds invalid value

12. Copyright BEA 2005, made available under EPL 1.0. | 12 Demo: annotation generates type

13. Copyright BEA 2005, made available under EPL 1.0. | 13 Agenda Background Simple Example Demo The mirror API and APT Pitfalls More Elaborate Example Futures

14. Copyright BEA 2005, made available under EPL 1.0. | 14 What you need to provide Step 1: Locate or write your own annotation(s) public @interface MyAnnotation { int num; String str; }

15. Copyright BEA 2005, made available under EPL 1.0. | 15 What you need to provide Step 2: Write an annotation processor factory import com.sun.mirror.apt.*; public class MyAnnotationFactory implements AnnotationProcessorFactory { AnnotationProcessor getProcessorFor() … }

16. Copyright BEA 2005, made available under EPL 1.0. | 16 What you need to provide Step 3: Write an annotation processor import com.sun.mirror.apt.*; public class MyAnnotationProcessor implements AnnotationProcessor { void process() }

17. Copyright BEA 2005, made available under EPL 1.0. | 17 Packaging You provide The annotation declaration An implementation of AnnotationProcessorFactory An implementation of AnnotationProcessor These are packaged in a jar Processor runs inside a dispatching framework Command line APT org.eclipse.jdt.apt.core plugin

18. Copyright BEA 2005, made available under EPL 1.0. | 18 Environment APIs Annotation Processor Environment Type system exploration File generation Error messages Declarations to process @Foo @Bar @Baz... b a c d

19. Copyright BEA 2005, made available under EPL 1.0. | 19 Using AnnotationProcessorEnvironment AnnotationProcessorEnvironment getDeclarationsWith(annotation) Declaration AnnotationMirror Element map getAnnotationMirrors() getElementValues()

20. Copyright BEA 2005, made available under EPL 1.0. | 20 Processing rounds Round 1: Original source files Round 3: Types generated in round 2 Round 2: Types generated by processing original files in round 1

21. Copyright BEA 2005, made available under EPL 1.0. | 21 “Write once” – processor reuse apt tool in JDK 1.5 or Eclipse apt plugin @MyAnno processor Eclipse apt plugin or apt tool in JDK 1.5

22. Copyright BEA 2005, made available under EPL 1.0. | 22 Dispatching: command line support apt Tool available in JDK 1.5 (along with javac, javadoc, javap, etc.) Works like javac, but with something extra: It runs 3 rd party annotation processors in addition to compiling source code Any generated types also get compiled Locates factories through META-INF/services/ com.sun.mirror.apt.AnnotationProcessorFactory file: Each line of file = fully qualified factory class name % apt –classpath Proc.jar MyProgram.java

23. Copyright BEA 2005, made available under EPL 1.0. | 23 Dispatching: inside Eclipse From a jar file external to the workspace Classpath variables provide indirection From a jar file inside a project Static jar only: jar file may not be rebuilt in same workspace that uses it Jar file must be available on the Eclipse Java compiler runtime classpath From a plugin Debugging must be done in plugin: Build in development workspace Run on annotated source in debugged workspace

24. Copyright BEA 2005, made available under EPL 1.0. | 24 Eclipse APT configuration UI

25. Copyright BEA 2005, made available under EPL 1.0. | 25 Agenda Background Simple Example Demo The mirror API and APT Pitfalls More Elaborate Example Futures

26. Copyright BEA 2005, made available under EPL 1.0. | 26 Pitfall: APT round implemenation @Foo class Quack @Roo class Mumble Round 1 @Goo class Moo @Bar class GenQuack @Bar class GenMumble @Bar class GenMoo Round 2 All of round 1 runs first Then all of round 2

27. Copyright BEA 2005, made available under EPL 1.0. | 27 Pitfall: Eclipse round implementation @Foo class Quack @Roo class Mumble Round 1 @Goo class Moo @Bar class GenQuack @Bar class GenMumble @Bar class GenMoo Round 2 Dispatch all this Rounding in Eclipse must be file-at-a-time for performance reasons. Then this

28. Copyright BEA 2005, made available under EPL 1.0. | 28 Pitfall: gathering generated files Don’t do this. It depends on dispatcher implementation. Instead: gather generated files in a post-build step. @Foo class Quack @Roo class Mumble @Goo class Moo @Bar class GenX Foo.xml Roo.xml Goo.xml Round 1 generates Round 2 reads all

29. Copyright BEA 2005, made available under EPL 1.0. | 29 Pitfall: processor requests generated type Don’t do this. It depends on visibility of generated types. But: generated types can refer to other generated types. @Foo class Quack @Goo class Moo class GenBar @Bar class GenFoo class GenGoo Round 1 generates Round 2 generates Generated type refers to: OK Anno processor requests: not OK

30. Copyright BEA 2005, made available under EPL 1.0. | 30 Pitfall: APT round implemenation @Foo class Quack @Roo class Mumble Round 1 @Goo class Moo @Bar class GenQuack @Bar class GenMumble @Bar class GenMoo Round 2 All of round 1 runs first Then all of round 2

31. Copyright BEA 2005, made available under EPL 1.0. | 31 Pitfall: build vs. reconcile Interactive (as you type) compilation = reconcile Can’t put new files on disk File generation happens only during build Best practice: build your workspace before you edit Then reconcile can see generated types Less confusion for the user Set project autobuild (build on Save) to “on” Keep build current Hopefully reconcile limitation goes away in next release

32. Copyright BEA 2005, made available under EPL 1.0. | 32 Agenda Background Simple Example Demo The Mirror API and APT Pitfalls More Elaborate Example Futures

33. Copyright BEA 2005, made available under EPL 1.0. | 33 Example: the Chargeable annotation App developer annotates a class to use the accounting system: Class level annotation: @Chargeable Method level annotations: @ChargePerCall(amount = 0.003) @ChargeWallClockTime @NoCharge

34. Copyright BEA 2005, made available under EPL 1.0. | 34 What does @Chargeable do? class SomeService @ChargeWallClock executeRequest() start = currentTimeMillis(); _service.executeRequest(); AccountSystem.charge( currentTimeMillis() – start); class SomeServiceWrapper private SomeService _service; public executeRequest() Generates wrapper class with proxy method that posts charge Generates ISomeService interface; both wrapper and app class implement Generates factory that creates the wrapped SomeService class

35. Copyright BEA 2005, made available under EPL 1.0. | 35 Code Snippet: using @Chargeable @Chargeable public class AnalysisService { @ChargeWallClockTime public ResultSet executeQuery(String key) { … } @ChargePerCall(amount =.007) public int findMedianSalary(ResultSet res) { … } @NoCharge public int findMeanSales(ResultSet res) { … }

36. Copyright BEA 2005, made available under EPL 1.0. | 36 @Chargeable generates source files Generated source User’s code

37. Copyright BEA 2005, made available under EPL 1.0. | 37 Agenda Background Simple Example Demo The Mirror API and APT Pitfalls More Elaborate Example Futures JSR 269 UI Enhancements

38. Copyright BEA 2005, made available under EPL 1.0. | 38 JSR 269 Annotations already standard language feature (JSR 175) Standard annotations exist for specific applications (JSR 181, 220) The mirror API is a preview interface (com.sun.mirror) Sun has announced intention to open-source interfaces JSR 269 will standardize the processor API (in javax package space) Specification will wrap up soon, to be available in Java SE 6 Target Eclipse availablity: 3.2 Mirror support continues in Eclipse until 269 widely adopted

39. Copyright BEA 2005, made available under EPL 1.0. | 39 User Interface APIs Eclipse apt plugin @MyAnno processor factory

40. Copyright BEA 2005, made available under EPL 1.0. | 40 Eclipse-specific functionality Code assistance inside annotation values Auto-completion Quick-fix Visual editing A special viewer/editor for annotations Refactoring Participation in rename operations Find-uses

41. Copyright BEA 2005, made available under EPL 1.0. | 41 Code assistance: auto-completion User presses Ctrl-space Annotation processor proposes content

42. Copyright BEA 2005, made available under EPL 1.0. | 42 Code assistance: quick-fix Annotation processor posts an error or warning User presses Ctrl-1 Annotation processor can propose fixes to the user

43. Copyright BEA 2005, made available under EPL 1.0. | 43 Visual Annotation Editor @MyService( buffer = @MessageBuffer(enable = true), conversation = @Phase(“start”) ) public boolean testVerifyFunds(Mumble m) { … } Show complex annotations in friendlier way Property pane-like UI Values in code in bold typeface Defaulted values in normal typeface Make nested annotations understandable

44. Copyright BEA 2005, made available under EPL 1.0. | 44 Release Timeline: APT in Eclipse JUNJULAUGSEPOCTNOVDECJANFEBMARAPRJUN Alpha (core) 3.1 Beta (UI Features) APT released as part of JDT 3.2 3.1.1

45. Copyright BEA 2005, made available under EPL 1.0. | 45 Q & A Try it out! Download and install at: http://www.eclipse.org/jdt/apt/introToAPT.html http://www.eclipse.org/jdt/apt/introToAPT.html

46. Copyright BEA 2005, made available under EPL 1.0 | 46 Using Java Annotations in Eclipse Gary Horen BEA Systems Tim Wagner BEA Systems