Bridging the Gap: J2SE 5.0 Annotations

It takes a long time for the Java community to fully absorb a
major new JDK release; it seems to take about two more releases
after a brand new version of the JDK before everything settles
down. Application server vendors don't always
fully support dot-zero releases right away; IDE, profiler, and
other tool support can lag; many new bugs have to be fixed; and
businesses are leery of building on anything so new. Those of
us on MacOS X who have not snagged a beta DVD have to wait until
Tiger comes out in the first half of 2005 to use Java 5.0.
The latter obstacle got me interested in how to co-opt some J2SE 5.0
features earlier rather than later.

In the interim, we have time to learn and
experiment--probably about a year, depending on
how conservative you are about new technology. This article talks
about strategies to bridge yourself to one new 5.0 feature
without making the full leap: annotations.

What Are Annotations?

JSR-175,
part of the 5.0 specification in the Java Community Process,
describes a proposed "metadata facility" for Java. Perhaps a more apt description
would be metacoding: annotations are code fragments that
elaborate upon and describe Java classes, methods, and fields.
They're implemented as a special kind of
interface and can be packaged, compiled, and imported like any
other class.

Markers

A marker annotation is a short-form where the presence of the
annotation provides all the information you'd
need. For example, we'll
consider how a hypothetical OODBMS might use annotations to mark
code. Let's say the designers decided they
wanted to make their persistence mechanism totally independent of
Java serializability, and thus wanted to avoid using
the Serializable interface and the transient
reserved word. Two examples of markers might be having one to
indicate that a class is persistent and another to mark a field as
transient.

The OODBMS could then recognize a class used in the context of
a transaction as a persistent one and store and update it
accordingly. It might also respect the class's
wishes by ignoring a temporary field value marked as
@Transient.

Single value

Most annotations need to take parameters, but for the special
case of a single value, the annotation spec provides a shorthand.
Let's say we want to declare a version number
for our persistent class. Here's one way:

In general, a single-parameter annotation takes the form, @Annotation(param-value). It's
a slightly more compact rendering of @Annotation(value=param-value).

Normal annotations

Most of the time, you want to provide more structured
information about a piece of code, more than just a single
attribute. In this case, annotations let you specify one or more
name-value pairs. The values can be Java primitives (ints,
Strings, doubles, boolean
values, etc.) or other annotations.
This lets you create quite complex structures while maintaining
type safety, one of the benefits of the new
annotations specification over traditional Doclet tags.
Revisiting our version number, we might want to enforce a
structure to it:

@Persistable
@Version(major=1, minor=0, micro=0)
public class Foo { }

The compiler and a syntax-aware IDE with support for 5.0, like
IntelliJ IDEA 4.0 or
Eclipse 3.1 (in beta),
can recognize proper use of our new Version annotation
immediately, for instance, recognizing a misspelling of one of the fields.

Arrays

Annotations can have multi-valued fields by using the array
syntax. For instance, let's say we wanted to
replace the Javadoc author fields, which allow multiple
values:

@Authors({
@Author("Jane Doe")
@Author("John Doe")
})

You can nest arrays inside arrays and complex annotations
inside arrays. If you can't represent your
metacode as an annotation, you probably are trying to do too much
with it. The syntax is quite powerful.

Declaring Your Own Annotations

An annotation is declared in a struct-like form with named and
typed fields, nested enumerations, if needed, and—like
interfaces—no code. They're pure data structures that
can ultimately get boiled down to extra JVM bytecode attributes
for the methods, fields, and types they annotate.

C'mon, Arthur! Get meta with me!

Annotation declarations can have their own annotations, which
I guess would be meta-metacoding. The specification calls them
"Meta Attributes." For instance,
the @Target annotation specifies what kinds of Java language
elements your application is allowed to modify:
@Target(ElementType.TYPE) would restrict it to modifying
enumerations, classes, or interfaces;
@Target(ElementType.CONSTRUCTOR) limits it to constructors; and
so on.

The @RetentionPolicy annotation tells the compiler what to do
with the annotation: SOURCE discards it, CLASS embeds it in the
classfile (the default), and RUNTIME makes it available via
reflection.

Let's say our OODBMS has a very smart
class-loader that can look at bytecodes as they enter the JVM, so that we don't really need reflection. Our Version
annotation might look like the following: