|
Metadata are data about data. In the context of computer programs, metadata are data about the code. A good example for metadata is Javadoc comments. The comments describe the code, but they do not modify its meaning. Starting with JDK 5.0, you can use annotations to insert arbitrary data into your source code. Why would you want to do this? Metadata are only useful in conjunction with tools. As we write this chapter, there are many promises that useful tools will soon appear. This chapter introduces you to the syntax for annotations and gives examples that demonstrate some of the possibilities. This should help you evaluate the tools that will emerge, and it might even give you ideas for building your own tools. Here is an example of a simple annotation: public class MyClass { . . . @TestCase public void checkRandomInsertions() } The annotation @TestCase annotates the checkRandomInsertions method. In Java, an annotation is used like a modifier, and it is placed before the annotated item, without a semicolon. (A modifier is a keyword such as public or static.) The name of each annotation is preceded by an @ symbol, similar to Javadoc comments. However, Javadoc comments occur inside /** . . . */ delimiters, whereas annotations are part of the code. By itself, the @TestCase annotation does not do anything. It needs a tool to be useful. For example, a testing tool might call all methods that are labeled as @TestCase when testing a class. Another tool might remove all test methods from a class file so that they are not shipped with the program after it has been tested. NOTE
Annotations can be defined to have elements, such as @TestCase() These elements can be processed by the tools that read the annotations. Other forms of elements are possible; we discuss them later in this chapter. Besides methods, you can annotate classes, fields, and local variablesan annotation can be anywhere you could put a modifier such as public or static. Each annotation must be defined by an annotation interface. The methods of the interface correspond to the elements of the annotation. For example, a TestCase annotation could be defined by the following interface: import java.lang.annotation.*; @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface TestCase { String id() default "[none]"; } The @interface declaration creates an actual Java interface. Tools that process annotations receive objects that implement the annotation interface. A tool would call the id method to retrieve the id element of a particular TestCase annotation. The Target and Retention annotations are meta-annotations. They annotate the TestCase annotation, marking it as an annotation that can be applied to methods only and that is retained when the class file is loaded into the virtual machine. We discuss these meta-annotations in detail on page 953. You have now seen the basic concepts of program metadata and annotations. In the next section, we walk through a concrete example of annotation processing. |
|