Recipe 23.3 Beyond JavaDoc: AnnotationsMetadata (JDK 1.5) and XDoclet

Recipe 23.3 Beyond JavaDoc: Annotations/Metadata (JDK 1.5) and XDoclet

Problem

You want to generate not just documentation, but also other code artifacts, from your source code. You want to mark code for additional compiler verification.

Solution

Download and use XDoclet. Or, in 1.5, use the Annotations or Metadata facility.

Discussion

XDoclet is a free tool that you can download from http://xdoclet.sourceforge.net. In addition to generating documentation, XDoclet can generate other "artifacts." For example, when writing an RMI program (see Chapter 22), you need to write not only the client and server but also the interface between them. With Enterprise JavaBeans, you need to write both a home and a remote interface. XDoclet reads additional @ tags in your source code and uses these to generate these little artifacts mechanically, the goal being to save you time and typing. For example, in generating Enterprise JavaBeans (EJBs), each Enterprise Bean which is normally written as a single Bean class may have a local and remote Home and Business interface. Each of these four artifacts is just an interface for some of the methods in the Bean itself. Also, at least one XML-based deployment descriptor is required by the EJB specification, in addition to one for each different brand of application server that you wish to deploy into. This makes for a great deal of busywork handcoding all these artifacts.

Enter XDoclet, the "attribute-oriented programming" tool.^[2] XDoclet reads a variety of special @ tags in a "doc comment" before the class and before methods and fields describing, for example, which methods go into which interface in the case of an EJB. A slightly marked up EJB might begin like this (imports omitted):

^[2] Not to be confused with Aspect Oriented Programming (see http://aopalliance.sourceforge.net/). Aspect Oriented Programming aims to provide a simpler alternative to EJBs and other heavyweight frameworks. But I digress....

/**  * This  Shopping Cart Stateful Session bean is really an example of the XDoclet EJB  tags.  * @see Product  * @ejb.bean  *      name="store/Cart"  *      type="Stateful"  *      jndi-name="store/Cart"  * @ejb.interface  *      remote-  * @version $Id: ch23.xml,v 1.5 2004/05/04 20:13:53 ian Exp $  */ public class XDocletDemo implements SessionBean {         /** @ejb.interface-method          */         public void add(Product o) {                cartItems.add(o);         } }

For both the class and the method, the @ejb... tags inform XDoclet how to fabricate the various EJB artifacts. This extra markup, and a series of Ant elements, are all that is needed to generate all the artifacts.

XDoclet has been successful and has grown immensely. Its EJB support now includes all major types, all major application servers, and even code for automatically implementing many EJB-related design patterns, such as Data Accessor Object (DAO). XDoclet also supports other types of classes such as JavaBeans, web applications, and others in short, any time one class can be generated mechanically from another.

23.3.4 The Annotations Mechanism (JDK 1.5)

The continuing success of XDoclet has led to a demand for a similar mechanism to be included as part of standard Java. The new 1.5 annotations are the result. The Annotations mechanism uses an interface-like syntax in which both declaration and use of Annotations see the name preceded by an at character (@). This was chosen, according to the designers, to be reminiscent of "Javadoc tags, a preexisting ad hoc annotation facility in the Java programming language." Javadoc is ad hoc only in the sense that its @ tags were never fully integrated into the language; most were ignored by the compiler, but @deprecated was always understood by the compiler (see Recipe 1.9).

Annotations can be read at runtime by use of the Reflection API; this is not discussed here (but see Chapter 25 for general information on the Reflection API). More commonly, annotations can be read before compile time by tools such as the RMI and EJB stub generators (and others to be invented, perhaps by you, gentle reader, in the post-1.5 release period!).

Annotations are also read by javac at compile time to provide extra information to the compiler. For example, a common coding error is overloading a method when you mean to override it, by mistakenly using the wrong argument type. Consider overriding the equals method in Object, if you mistakenly write:

public boolean equals(MyClass obj) { }

then you have created a new overload, that will likely never be called, and the default version in object will be called. To prevent this, one of several new Annotations provided in java.lang is the Overrides annotation. This has no parameters but simply is placed before the method call. For example:

/** Simple demonstation of Metadata being used to verify  * that a method does in fact override (not overload) a method  * from the parent class. This class provides the method.  */ abstract class Top {     public abstract void myMethod(Object o); } /** Simple demonstation of Metadata being used to verify  * that a method does in fact override (not overload) a method  * from the parent class. This class is supposed to do the overriding,  * but deliberately introduces an error to show how the 1.5 compiler  * behaves (-source 1.5 required).  */ class Bottom {     @Overrides public void myMethod(String s) {    // EXPECT COMPILE ERROR         // Do something here...     } }

Running this (with -source 1.5) results in a compiler error that the method in question does not override a method, even though the annotation says it does; this is a fatal compile-time error:

> javac OverridesDemo.java OverridesDemo.java:16: method does not override a method from its superclass         @Overrides public void myMethod(String s) {     // EXPECT COMPILE ERROR          ^ 1 error >

A list of other annotations provided in 1.5 for use by Java developers is included in the online documentation that accompanies the release.

Finally, the Javadoc Doclet interface has been extended to allow reading of Annotations before compile time by programs that wish to generate other code artifacts. See the Doclet API documentation with JDK 1.5 for details on using this mechanism.