Professional Documents
Culture Documents
an introduction to
Walter Harley BEA Systems Inc.
2008 by BEA Systems Inc.; made available under the EPL v1.0 | 3/18/2008 | Java Annotations
Introduction
Walter Harley, BEA Systems Inc. JDT APT lead; Eclipse committer since 2005 Caveat: I am not a J2EE developer
Who am I?
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
usage
Program metadata decorations on ordinary Java code. Like javadoc comments, but with syntax and strong types. Meant to be both human- and machine-readable. No relation to Eclipse editor annotations!
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Previously, generation was achieved via xdoclet or custom tools like ejbgen (v2.0), using javadoc comments as input. But programming in javadoc is unchecked and syntactically limited. Annotations are a solution. JSR-175 introduced annotations into Java 5, in 2004
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
Introduction How are annotations used? How do annotations fit into the language? Whats on the horizon? Q&A
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotations as standardized comments e.g., @Deprecated, versus /* dont use this any more */
Harder to mis-spell, easier to search, and less ambiguous.
Defined entities (@deprecated) in javadoc are pretty good; but @depracated in javadoc fails silently. No programmatic access to the annotation implied in this case, its just there for humans to read.
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotations let you tell the compiler/IDE what you mean, in more detail than the raw code will support. Integrity analysis (e.g., @NonNull in IntelliJ)
Requires proprietary support built into the compiler/IDE
Semantic error checking, e.g., only one method in an EntityBean should be a primary key.
May be implemented with an annotation processor
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Practical examples: EJB, JAX-WS Not well suited to composite files (message.properties, web-info.xml), because of incremental compilation
Can make composites in separate build step, or during deploy
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Can modify existing class which APT doesnt let you do. Practical example: Resin app server
@TransactionAttribute(REQUIRED) inserts transaction locking code around calls that need to be atomic.
Other possibilities: load class differently depending on threading requirements, API version requirements, etc.
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
JUnit 4 test runner finds annotated classes, instantiates them, executes the annotated methods Test case classes dont need to subclass TestCase
@Test(expected = IndexOutOfBoundsException.class) public void empty() { List l = new ArrayList<Object>(); l.get(0); // should throw exception }
10
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Ill discuss how to read annotations at runtime after a bit of language background.
11 Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
Introduction How are annotations used? How do annotations fit into the language? Whats on the horizon? Q&A
12
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
usage (MyClass.java)
A marker annotation is the simplest type of annotation No member values just presence or absence of the annotation
13
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
usage
A full or normal annotation is one with multiple members Again, a lot like declaring an interface, except...
You can specify default values for members Lots of restrictions on members, which well get to in a moment
If all a full annotations members have defaults, it can be used like a marker annotation.
14
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
usage
Only one member, named value. Can then omit the value= when using the annotation. The value member can have a default.
Lets it be used like a marker annotation
15
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Can declare constants, enums, and inner types. In bytecode, an annotation type is an interface, with a flag.
16
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
An ordinary class or interface can implement or extend an annotation type Variables can be of annotation type. Normally youd only see this in code that was reflecting on annotations, not in the annotated code itself. In practice, implementing an annotation type is unusual, and compilers may warn!
17 Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Cannot be generic. Cannot explicitly extend any other interfaces. Methods cannot have any parameters Methods cannot have any type parameters Method declarations cannot have a throws clause
Intended use: passing around simple declarative metadata.
18 Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Primitive types (int, boolean, ...) and String Class enum Annotation (but not the annotation being defined) and one-dimensional arrays of the above.
19
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Syntactically, annotations are modifiers, like final. Annotations can be applied to any declaration: types (including enums and annotation types), fields, constructors, methods, parameters, enum constants, packages, and local variables.
Roughly speaking, the same things that youd javadoc. JSR-308 seeks to extend the set of things that can be annotated.
Can put multiple annotations on one element, but they must each be of a different annotation type.
Work around this with annotations that contain arrays of annotations
20
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Package annotations
// file package-info.java: @Deprecated package p; // no other contents in file
Example use case: deprecate an entire package with @Deprecated But packages usually have multiple declarations! By convention, annotate only one of them, in a file named package-info.java.
Analogous to package-info.html for javadoc Because this name contains a dash, it is not a legal identifier; so, cannot contain a primary type.
Package declaration comes before import statements, so must use qualified name for annotations from other packages.
21
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Member values cannot be null (but can be an empty array or String) Values must be constant expressions
I.e., computed statically at compile time
22
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
23
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Built-in annotations
@Deprecated class Y { public abstract int foo(); } class X extends Y { @SuppressWarnings(unchecked) List numbers; @Override public int foo() { ... } }
Defined in java.lang; support built into the compiler or IDE. @Deprecated warns when deprecated item is used @SuppressWarnings turns off compiler warnings
There is no standard list of suppressible warnings
24
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
@Retention: does MyAnno get compiled into class file, and does it get loaded into the VM so it can be reflected on? Default is CLASS. @Target: to which elements can MyAnno be applied? @Documented: will MyAnno be mentioned in javadoc of the classes it is present on? (Is it part of the API contract?) @Inherited: if MyAnno is present on a class, is it inherited by subclasses? The built-in meta-annotations control how the tools (compiler, javadoc, VM) will treat an annotation.
25 Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Processors dont see source code directly; instead, they see a typesystem sort of like the Eclipse Java DOM.
No method bodies; just what the type looks like to other types
Like reflection API, except introspecting on source code at compile time, rather than on live objects at runtime.
26
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Resource to learn more: APT tutorial presented at EclipseCon 2007, available online at eclipse.org.
27
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Annotations have to explicitly be given @Retention(RUNTIME). Reflection is about the only way to create an in-memory instance of an annotation type (because annotations are interfaces).
28
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
Introduction How are annotations used? How do annotations fit into the language? Whats on the horizon? Q&A
29
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Currently these annotations are proprietary. Proposal is to standardize them so that the annotations, at least, can be shared across different tools.
Getting tools to support the annotations will be slower.
Discussion also underway of annotations relating to concurrency; and a long tail of other issues more or less related to defect detection.
@ThreadSafe, @EventThreadOnly, etc. @Taint @Positive, @Nonpositive, etc.
30
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Making use of such annotations, however, requires much deeper APIs for code inspection than we have now. Emphasis on compile-time checking; many of these constructs dont even exist at runtime.
31 Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Expect increased support within development tools JSR 305 (software quality annotations) will gain broader support slowly.
Implementations are proprietary, hard to leverage No plans yet in Eclipse?
32
Java Annotations | 2008 by BEA Systems Inc.; made available under the EPL v1.0
Agenda
Introduction How are annotations used? How do annotations fit into the language? Whats on the horizon? Q&A
@ Java Annotations
an introduction to
Walter Harley BEA Systems Inc.
2008 by BEA Systems Inc.; made available under the EPL v1.0 | 3/18/2008 | Java Annotations