Using Java Annotations in Eclipse
description
Transcript of Using Java Annotations in Eclipse
Copyright BEA 2005, made available under EPL 1.0 | 1
Using Java Annotationsin Eclipse
Gary Horen BEA SystemsTim Wagner BEA Systems
Copyright BEA 2005, made available under EPL 1.0. | 2
Agenda
Background
Simple Example Demo
Mirror API and APT
Pitfalls
More Elaborate Example
Futures
Copyright BEA 2005, made available under EPL 1.0. | 3
What are annotations?
Metadata placed directly in your source codeStandardized by JSR 175, added to Java in 1.5Intended to replace “xdoclet”-style programming with a modern, type-checked equivalent
@MyAnnotation(num=5, str=“hi”)public class Foo { …}
Copyright BEA 2005, made available under EPL 1.0. | 4
What are annotations?
Defined using Java – much like interfacesCan be used by both tools and runtimesEnable a simpler “POJO”-based programming model
public @interface MyAnnotation { int num; String str;}
Copyright BEA 2005, made available under EPL 1.0. | 5
What can an annotation do?
@WebservicePublic class Foo {
}
Endpoint Interface
XML-Java Bindings
Example: helping a POJO to become a web serviceAnnotations on user code generate helper objects
Endpoint interface: receives and parses XML message
Bindings embody the message as parameters to the POJO method
generates
Copyright BEA 2005, made available under EPL 1.0. | 6
Who uses annotations?
J2SE – builtin annotationsJ2EE – EBJ 3.0, JSR 181, JSR 250, JAXB 2.0, JAX-WS 2.03rd party frameworks: Hibernate, Beehive, Spring…and eventually every major IT organization
@Deprecated@WebService@Persistent@MyCorporateAnnotation
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 usefulSomething 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
Copyright BEA 2005, made available under EPL 1.0. | 8
Process viewProcessor Container
@MyAnnopublic class Foo{ ...}
Annotated Source File
apt tool in JDK 1.5 or
Eclipse apt plugincompiles
@MyAnno processor another processor
calls
Copyright BEA 2005, made available under EPL 1.0. | 9
What can an annotation processor do?
CanClaim a set of annotations
Check annotations for semantic errors
Generate new Java source files
Generate arbitrary data files (e.g. deployment descriptor)
CannotChange the bytecode generated when the file is compiled in any way
Copyright BEA 2005, made available under EPL 1.0. | 10
Demo
DemoAnnotationAn Annotation contains elements
Elements contain names and values
An annotation processor can check element values for correctness
TypeGeneratingAnnotationGenerates a Java source file
Copyright BEA 2005, made available under EPL 1.0. | 11
Demo: processor finds invalid value
Copyright BEA 2005, made available under EPL 1.0. | 12
Demo: annotation generates type
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
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;}
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()
…}
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()}
Copyright BEA 2005, made available under EPL 1.0. | 17
Packaging
You provideThe annotation declaration
An implementation of AnnotationProcessorFactory
An implementation of AnnotationProcessor
These are packaged in a jarProcessor runs inside a dispatching framework
Command line APT
org.eclipse.jdt.apt.core plugin
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
cd
Copyright BEA 2005, made available under EPL 1.0. | 19
Using AnnotationProcessorEnvironmentAnnotationProcessorEnvironment
getDeclarationsWith(annotation)Declaration
AnnotationMirror
Element map
getAnnotationMirrors()
getElementValues()
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
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
Copyright BEA 2005, made available under EPL 1.0. | 22
Dispatching: command line support
aptTool 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
Copyright BEA 2005, made available under EPL 1.0. | 23
Dispatching: inside Eclipse
From a jar file external to the workspaceClasspath 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
Copyright BEA 2005, made available under EPL 1.0. | 24
Eclipse APT configuration UI
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
Copyright BEA 2005, made available under EPL 1.0. | 26
Pitfall: APT round implemenation
@Fooclass Quack
@Rooclass Mumble
Round 1 @Gooclass Moo
@Barclass GenQuack
@Barclass GenMumble
@Barclass GenMoo
Round 2
All of round 1 runs first
Then all of round 2
Copyright BEA 2005, made available under EPL 1.0. | 27
Pitfall: Eclipse round implementation
@Fooclass Quack
@Rooclass MumbleRound 1 @Goo
class Moo
@Barclass GenQuack
@Barclass GenMumble
@Barclass GenMoo
Round 2
Dispatch all this
Rounding in Eclipse must be file-at-a-time for performance reasons.
Then this Then this
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.
@Fooclass Quack
@Rooclass Mumble
@Gooclass Moo
@Barclass GenX
Foo.xml Roo.xml Goo.xmlRound 1 generates
Round 2 reads all
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.
@Fooclass Quack
@Gooclass Moo
class GenBar
@Barclass GenFoo
class GenGoo
Round 1 generates
Round 2 generates
Generated type refers to: OK
Anno processor requests: not OK
Copyright BEA 2005, made available under EPL 1.0. | 30
Pitfall: APT round implemenation
@Fooclass Quack
@Rooclass Mumble
Round 1 @Gooclass Moo
@Barclass GenQuack
@Barclass GenMumble
@Barclass GenMoo
Round 2
All of round 1 runs first
Then all of round 2
Copyright BEA 2005, made available under EPL 1.0. | 31
Pitfall: build vs. reconcile
Interactive (as you type) compilation = reconcileCan’t put new files on disk
File generation happens only during buildBest 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
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
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: @ChargeableMethod level annotations:
@ChargePerCall(amount = 0.003)
@ChargeWallClockTime
@NoCharge
Copyright BEA 2005, made available under EPL 1.0. | 34
What does @Chargeable do?
class SomeService
@ChargeWallClockexecuteRequest()
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
Copyright BEA 2005, made available under EPL 1.0. | 35
Code Snippet: using @Chargeable
@Chargeablepublic class AnalysisService {
@ChargeWallClockTimepublic ResultSet executeQuery(String key){
…}
@ChargePerCall(amount = .007)public int findMedianSalary(ResultSet res){
…}
@NoChargepublic int findMeanSales(ResultSet res){
…}
Copyright BEA 2005, made available under EPL 1.0. | 36
@Chargeable generates source files
Generated source
User’s code
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
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 6Target Eclipse availablity: 3.2Mirror support continues in Eclipse until 269 widely adopted
Copyright BEA 2005, made available under EPL 1.0. | 39
User Interface APIs
Eclipse apt plugin
@MyAnno processor factory
Copyright BEA 2005, made available under EPL 1.0. | 40
Eclipse-specific functionality
Code assistance inside annotation valuesAuto-completion
Quick-fix
Visual editingA special viewer/editor for annotations
RefactoringParticipation in rename operations
Find-uses
Copyright BEA 2005, made available under EPL 1.0. | 41
Code assistance: auto-completion
User presses Ctrl-spaceAnnotation processor proposes content
Copyright BEA 2005, made available under EPL 1.0. | 42
Code assistance: quick-fixAnnotation processor posts an error or warningUser presses Ctrl-1Annotation processor can propose fixes to the user
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 wayProperty pane-like UI
Values in code in bold typeface
Defaulted values in normal typeface
Make nested annotations understandable
Copyright BEA 2005, made available under EPL 1.0. | 44
Release Timeline: APT in Eclipse
JUN JUL AUG SEP OCT NOV DEC JAN FEB MAR APR JUN
Alpha (core)
3.1
Beta (UI Features)
APT released as part of JDT
3.23.1.1
Copyright BEA 2005, made available under EPL 1.0. | 45
Q & ATry it out! Download and install at:http://www.eclipse.org/jdt/apt/introToAPT.html
Copyright BEA 2005, made available under EPL 1.0 | 46
Using Java Annotationsin Eclipse
Gary Horen BEA SystemsTim Wagner BEA Systems