Overview

What problems doe=
s Annogen solve?

=20

Annogen is a tool which helps you work with JSR175 annotations, a new fe=
ature in JDK 1.5. JSR175 is a much-needed improvement to java. However, a f=
ew challenges may lie in store for developers of frameworks which need to p=
rocess JSR175 annotations (hereafter, simply called frameworks). A=
nnogen aims to provide an elegant solution for the following problems:

=
=20

Annotation Overriding

=20

Because JSR175 annotations are 'baked-in' to .class files by javac, fram=
eworks have no elegant way to manipulate the annotation values that were de=
clared by the class author.

=20

Migration to JSR175 from=
Older JDKs

=20

Many existing projects may want to start using JSR175 annotations, but w=
ill still need to support older JDKs for some time. This migration presents=
a dilemma because JSR175 annotation types cannot even be classloaded witho=
ut JDK 1.5.

=20

Bridging Disparate Access=
Models

=20

Sun has provided new java.lang APIs for strongly-typed access to JSR175 =
annotation values. However, this can only be used to access annotations whi=
ch have a 'runtime retention policy;' annotations without this must be acce=
ssed via javadoc, which provides a completely different, untyped API for vi=
ewing annotations. Mediating between these two access models could be a pro=
blem for frameworks, particularly those which must access source artifacts =
not available via reflection, such as javadoc comments.

=20

What does Annogen do?

=20

Annogen uses your JSR175 annotation types to code-generate special java =
beans called AnnoBeans. AnnoBeans look exactly like your JSR175 an=
notations; in fact, they can actually directly implement your JSR175 annota=
tion interfaces. AnnoBeans carry exactly the same data that appears on your=
JSR175 annotations. You write your framework code to use AnnoBeans when it=
needs to understand what annotations are on a java class.

=20

Why is that useful?

=20

Overrides

=20

One big advantage to this approach stems from the fact that AnnoBeans ca=
n be modified. AnnoBeans start out reflecting the values on the actual anno=
tations they represent. You are then given the option to add, modify, or re=
move annotation values before they are consumed by your framework.

=20

JDK 1.4 support

=20

Another advantage is that you can run Annogen under JDK 1.4 and still lo=
ad AnnoBeans. In this case, you can retrieve metadata from other source (su=
ch as XML or javadoc tags) and expose it to your code though the same API a=
s your JSR175 annotations.

=20

Unified, strongly-typed ac=
cess

=20

A third advantage is that AnnoBeans can be used in conjunction with a va=
riety of Java introspection APIs, including reflection, javadoc, Mirror, QD=
ox, and JAM. (Support for other similar APIs can easily be added in the fut=
ure). This means that whether your framework is driven off of class files (=
via reflection) or java sources (via javadoc), you have a single, consisten=
t, strongly-typed API for viewing your annotations.

=20

What do I have to do to us=
e Annogen?

=20

Use of Annogen is divided into three distinct phases: Generate, Override=
, and View. Each phase has a corresponding sub-package in the Annogen class=
hierarchy.

=20

Generate

=20

In the generate phase, Annogen code-generates AnnoBeans from your JSR175=
annotation classes. This should be done as part of the build of your frame=
work, before your javac your framework sources. Annogen includes an ant tas=
k to make this easier. You will also need to make sure that each of your an=
notation classes are themselves annotated with a simple annotation, Annogen=
Info, which tells Annogen the name of the AnnoBean to be generated.

=20

Override

=20

Once you have your AnnoBeans, you can create an AnnoOverrider w=
hich adds, modifies, or remove AnnoBeans associated with a given java class=
. How and when this is done depends upon your needs. For example, say you h=
ad a 'cache size' deployment annotation which your users might occasionally=
want to override at deployment time. You could implement an AnnoOverrider =
which retrieves the user's override preferences (say, from an XML file) and=
then modifies the AnnoBeans accordingly.

=20

View

=20

In the final step, your framework code reads the AnnoBeans and uses them=
to do something interesting with them, such as deploy a user application. =
You retrieve instance of the AnnoBeans through the AnnoViewer inte=
rface. You simply ask the AnnoViewer to give you the AnnoBean for a given a=
nnotation type on a given class. The AnnoBean you get back may or may not h=
ave been modified by your AnnoOverrider; the nice thing is here that you do=
n't have to care. Annogen allows you to maintain a clean separation between=
the code which gathers and manipulates annotation values and the code whic=
h acts on those values.

=20

Can AnnoB=
eans implement my JSR175 AnnotationTypes?

=20

In the Generate phase, you have an option called implementAnnotation=
Types. If true, the generated AnnoBeans will directly implement your J=
SR175 types. The advantage to this approach is that your framework code in =
the View phase does not ever have to know about AnnoBeans - you just use JS=
R175 annotation types just as you would with regular reflection. They will =
be implemented by AnnoBeans, but your code doesn't have to know that. This =
approach is somewhat simpler, cleaner and may make it easier to integrate w=
ith other code which use the same JSR175 types.

=20

The only disadvantage to it is that you sacrifice compatibility withh ol=
der JDKs, where your JSR175 annotation types won't even classload. But if J=
DK 1.4 support is not important to you, then you probably should set implem=
entAnnotationTypes to true and write your View-phase code against your JSR1=
75 types.

=20

Note that in either case, your Override-phase code still must import Ann=
oBeans (because JSR175 types don't have setters) and your View-phase code n=
eeds to use an AnnoViewer (because the JDK doesn't know about your override=
s).