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

Using Java Annotations in Eclipse

  • Upload
    eithne

  • View
    70

  • Download
    0

Embed Size (px)

DESCRIPTION

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 - PowerPoint PPT Presentation

Citation preview

Page 1: 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

Page 2: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 2

Agenda

Background

Simple Example Demo

Mirror API and APT

Pitfalls

More Elaborate Example

Futures

Page 3: Using Java Annotations in Eclipse

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 { …}

Page 4: Using Java Annotations in Eclipse

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;}

Page 5: Using Java Annotations in Eclipse

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

Page 6: Using Java Annotations in Eclipse

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

Page 7: Using Java Annotations in Eclipse

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

Page 8: Using Java Annotations in Eclipse

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

Page 9: Using Java Annotations in Eclipse

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

Page 10: Using Java Annotations in Eclipse

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

Page 11: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 11

Demo: processor finds invalid value

Page 12: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 12

Demo: annotation generates type

Page 13: Using Java Annotations in Eclipse

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

Page 14: Using Java Annotations in Eclipse

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;}

Page 15: Using Java Annotations in Eclipse

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()

…}

Page 16: Using Java Annotations in Eclipse

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()}

Page 17: Using Java Annotations in Eclipse

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

Page 18: Using Java Annotations in Eclipse

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

Page 19: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 19

Using AnnotationProcessorEnvironmentAnnotationProcessorEnvironment

getDeclarationsWith(annotation)Declaration

AnnotationMirror

Element map

getAnnotationMirrors()

getElementValues()

Page 20: Using Java Annotations in Eclipse

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

Page 21: Using Java Annotations in Eclipse

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

Page 22: Using Java Annotations in Eclipse

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

Page 23: Using Java Annotations in Eclipse

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

Page 24: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 24

Eclipse APT configuration UI

Page 25: Using Java Annotations in Eclipse

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

Page 26: Using Java Annotations in Eclipse

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

Page 27: Using Java Annotations in Eclipse

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

Page 28: Using Java Annotations in Eclipse

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

Page 29: Using Java Annotations in Eclipse

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

Page 30: Using Java Annotations in Eclipse

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

Page 31: Using Java Annotations in Eclipse

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

Page 32: Using Java Annotations in Eclipse

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

Page 33: Using Java Annotations in Eclipse

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

Page 34: Using Java Annotations in Eclipse

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

Page 35: Using Java Annotations in Eclipse

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){

…}

Page 36: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 36

@Chargeable generates source files

Generated source

User’s code

Page 37: Using Java Annotations in Eclipse

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

Page 38: Using Java Annotations in Eclipse

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

Page 39: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 39

User Interface APIs

Eclipse apt plugin

@MyAnno processor factory

Page 40: Using Java Annotations in Eclipse

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

Page 41: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0. | 41

Code assistance: auto-completion

User presses Ctrl-spaceAnnotation processor proposes content

Page 42: Using Java Annotations in Eclipse

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

Page 43: Using Java Annotations in Eclipse

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

Page 44: Using Java Annotations in Eclipse

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

Page 45: Using Java Annotations in Eclipse

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

Page 46: Using Java Annotations in Eclipse

Copyright BEA 2005, made available under EPL 1.0 | 46

Using Java Annotationsin Eclipse

Gary Horen BEA SystemsTim Wagner BEA Systems