One of the latest trends in programming, particularly in Java programming, is the use of metadata. Metadata, simply put, is data about data. Metadata can be used to create documentation, to track down dependencies in code, and even to perform rudimentary compile-time checking. A rash of tools for metadata, such as XDoclet (see Resources), add these features to the core Java language and have been part of the Java programming landscape for a while.

Until the availability of J2SE 5.0 (aka Tiger, now in its second beta release), the core Java language came closest to a metadata facility with the Javadoc methodology. You use a special set of tags to mark up your code and then execute the javadoc command to turn the tags into a formatted HTML page that documents the classes the tags are attached to. Javadoc is an inadequate metadata tool, though, because you have no solid, practical, standardized way to get at the data for any purpose other than generating documentation. The fact that HTML code is often mixed into the Javadoc output decreases its value for any other purpose even further.

Tiger incorporates a far more versatile metadata facility into the core Java language through a new feature called annotations. Annotations are modifiers you can add to your code and apply to package declarations, type declarations, constructors, methods, fields, parameters, and variables. Tiger includes built-in annotations and also supports custom annotations you can write yourself. This article will give you an overview of metadata's benefits and introduce you to Tiger's built-in annotations. Part 2 in this article series will explore custom annotations. My thanks to O'Reilly Media, Inc., which has graciously allowed me to use the code sample from the annotations chapter of my book on Tiger for this article (see Resources).

The value of metadata

In general, metadata's benefits fall into three categories: documentation, compiler checking, and code analysis. Code-level documentation is the most-often-cited use. Metadata provides a helpful way to indicate if methods are dependent on other methods, if they are incomplete, if a certain class must reference another class, and so on. This is indeed useful, but documentation is probably the least relevant reason for adding metadata to the Java language. Javadoc already provides a fairly easy-to-understand and robust way to document code. Besides, who wants to write a documentation tool when one already exists and works fine for the most part?