1 / 46

Using Java Annotations in Eclipse

Using Java Annotations in Eclipse. Gary Horen BEA Systems Tim Wagner BEA Systems. Agenda. Background Simple Example Demo Mirror API and APT Pitfalls More Elaborate Example Futures. What are annotations?. Metadata placed directly in your source code

eithne
Télécharger la présentation

Using Java Annotations in Eclipse

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  1. Using Java Annotationsin Eclipse Gary Horen BEA Systems Tim Wagner BEA Systems

  2. Agenda • Background • Simple Example Demo • Mirror API and APT • Pitfalls • More Elaborate Example • Futures

  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. 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. What can an annotation do? • 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 Endpoint Interface generates @WebservicePublic class Foo { } XML-Java Bindings

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

  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. Process view Processor Container Annotated Source File apt tool in JDK 1.5 or Eclipse apt plugin @MyAnno public class Foo { ... } compiles calls @MyAnno processor another processor

  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. 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. Demo: processor finds invalid value

  12. Demo: annotation generates type

  13. Agenda • Background • Simple Example Demo • The mirror API and APT • Pitfalls • More Elaborate Example • Futures

  14. What you need to provide • Step 1: Locate or write your own annotation(s) public @interface MyAnnotation { int num; String str; }

  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. What you need to provide • Step 3: Write an annotation processor import com.sun.mirror.apt.*; public class MyAnnotationProcessor implements AnnotationProcessor { void process() }

  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. Environment APIs Annotation Processor Environment @Foo @Bar @Baz ... a d c b Declarations to process Type system exploration File generation Error messages

  19. Using AnnotationProcessorEnvironment AnnotationProcessorEnvironment getDeclarationsWith(annotation) Declaration getAnnotationMirrors() AnnotationMirror getElementValues() Element map

  20. Processing rounds Round 1: Original source files Round 2: Types generated by processing original files in round 1 Round 3: Types generated in round 2

  21. “Write once” – processor reuse apt tool in JDK 1.5 or Eclipse apt plugin Eclipse apt plugin or apt tool in JDK 1.5 @MyAnno processor

  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 3rd 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. 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 • <extension point=org.eclipse.jdt.apt.core.annotationProcessorFactory> • Debugging must be done in plugin: • Build in development workspace • Run on annotated source in debugged workspace

  24. Eclipse APT configuration UI

  25. Agenda • Background • Simple Example Demo • The mirror API and APT • Pitfalls • More Elaborate Example • Futures

  26. Pitfall: APT round implemenation All of round 1 runs first @Fooclass Quack @Gooclass Moo @Rooclass Mumble Round 1 Then all of round 2 @Barclass GenMoo @Barclass GenQuack @Barclass GenMumble Round 2

  27. Pitfall: Eclipse round implementation Dispatch all this Then this Then this @Fooclass Quack @Gooclass Moo @Rooclass Mumble Round 1 @Barclass GenQuack @Barclass GenMumble @Barclass GenMoo Round 2 Rounding in Eclipse must be file-at-a-time for performance reasons.

  28. Pitfall: gathering generated files @Fooclass Quack @Gooclass Moo @Rooclass Mumble • Don’t do this. It depends on dispatcher implementation. • Instead: gather generated files in a post-build step. Round 1 generates Goo.xml Roo.xml Foo.xml @Barclass GenX Round 2 reads all

  29. Pitfall: processor requests generated type @Gooclass Moo @Fooclass Quack • Don’t do this. It depends on visibility of generated types. • But: generated types can refer to other generated types. Round 1 generates @Barclass GenFoo class GenGoo Round 2 generates Anno processor requests: not OK class GenBar Generated type refers to: OK

  30. Pitfall: APT round implemenation All of round 1 runs first @Fooclass Quack @Gooclass Moo @Rooclass Mumble Round 1 Then all of round 2 @Barclass GenMoo @Barclass GenQuack @Barclass GenMumble Round 2

  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. Agenda • Background • Simple Example Demo • The Mirror API and APT • Pitfalls • More Elaborate Example • Futures

  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. What does @Chargeable do? • 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 class SomeServiceWrapper private SomeService _service; class SomeService public executeRequest() start = currentTimeMillis();_service.executeRequest();AccountSystem.charge( currentTimeMillis() – start); @ChargeWallClockexecuteRequest()

  35. Code Snippet: using @Chargeable @Chargeablepublic class AnalysisService { @ChargeWallClockTime public ResultSet executeQuery(String key) { … } @ChargePerCall(amount = .007) public int findMedianSalary(ResultSet res) { … } @NoCharge public int findMeanSales(ResultSet res) { … }

  36. @Chargeable generates source files Generated source User’s code

  37. Agenda • Background • Simple Example Demo • The Mirror API and APT • Pitfalls • More Elaborate Example • Futures • JSR 269 • UI Enhancements

  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. User Interface APIs Eclipse apt plugin @MyAnno processor factory

  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. Code assistance: auto-completion • User presses Ctrl-space • Annotation processor proposes content

  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. Visual Annotation Editor • 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 @MyService( buffer = @MessageBuffer(enable = true), conversation = @Phase(“start”))public boolean testVerifyFunds(Mumble m){ … }

  44. Release Timeline: APT in Eclipse JUN JUL AUG SEP OCT NOV DEC JAN FEB MAR APR JUN 3.1 3.2 3.1.1 Alpha (core) Beta (UI Features) APT released as part of JDT

  45. Q & A Try it out! Download and install at:http://www.eclipse.org/jdt/apt/introToAPT.html

  46. Using Java Annotationsin Eclipse Gary Horen BEA Systems Tim Wagner BEA Systems

More Related