Standard Annotations

JDK 5.0 defines seven annotation interfaces. Three of them are regular annotations that you can use to annotate items in your source code. The other four are meta-annotations that describe the behavior of annotation interfaces. Table 13-1 shows these annotations. We discuss them in detail in the following two sections.

Table 13-1. The Standard Annotations

Annotation Interface	Applicable To	Purpose
Deprecated	All	Marks item as deprecated
SuppressWarnings	All but packages and annotations	Suppresses warnings of the given type
Override	Methods	Checks that this method overrides a superclass method
Target	Annotations	Specifies the items to which this annotation can be applied
Retention	Annotations	Specifies how long this annotation is retained
Documented	Annotations	Specifies that this annotation should be included in the documentation of annotated items
Inherited	Annotations	Specifies that this annotation, when applied to a class, is automatically inherited by its subclasses.

Regular Annotations

The @Deprecated annotation can be attached to any items whose use is no longer encouraged. The compiler will warn when you use a deprecated item. This annotation has the same role as the @deprecated Javadoc tag.

The @SuppressWarnings annotation tells the compiler to suppress warnings of a particular type, for example,

 @SuppressWarnings("unchecked cast") 

The initial release of the JDK 5.0 compiler does not support this annotation.

The @Override annotation applies only to methods. The compiler checks that a method with this annotation really overrides a method from the superclass. For example, if you declare

 public MyClass {    @Override public boolean equals(MyClass other);    . . . } 

then the compiler will report an error. After all, the equals method does not override the equals method of the Object class. That method has a parameter of type Object, not MyClass.

Meta-Annotations

The @Target meta-annotation is applied to an annotation, restricting the items to which the annotation applies. For example,

 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) public @interface TestCase 

Table 13-2 shows all possible values. They belong to the enumerated type ElementType. You can specify any number of element types, enclosed in braces.

Table 13-2. Element Types for the @Target Annotation

Element Type	Annotation Applies To
ANNOTATION_TYPE	Annotation type declarations
PACKAGE	Packages
TYPE	Classes (including enum) and interfaces (including annotation types)
METHOD	Methods
CONSTRUCTOR	Constructors
FIELD	Fields (including enum constants)
PARAMETER	Method or constructor parameters
LOCAL_VARIABLE	Local variables

An annotation without an @Target restriction can be applied to any item. The compiler checks that you apply an annotation only to a permitted item. For example, if you apply @TestCase to a field, a compile-time error results.

The @Retention meta-annotation specifies how long an annotation is retained. You specify at most one of the values in Table 13-3. The default is RetentionPolicy.CLASS.

Table 13-3. Retention Policies for the @Retention Annotation

Retention Policy	Description
SOURCE	Annotations are not included in class files.
CLASS	Annotations are included in class files, but the virtual machine need not load them.
RUNTIME	Annotations are included in class files and loaded by the virtual machine. They are available through the reflection API.

In Example 13-2, the @ActionListenerFor annotation was declared with RetentionPolicy.RUNTIME because we used reflection to process annotations. In the following two sections, you will see examples of processing annotations at the source and class file levels.

The @Documented meta-annotation gives a hint to documentation tools such as Javadoc. Documented annotations should be treated just like other modifiers such as protected or static for documentation purposes. The use of other annotations is not included in the documentation. For example, suppose we declare @ActionListenerFor as a documented annotation:

 @Documented @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface ActionListenerFor 

Now the documentation of each annotated method contains the annotation, as shown in Figure 13-1.

Figure 13-1. Documented annotations

If an annotation is transient (such as @BugReport) or an implementation detail (such as @ActionListenerFor), then you should probably not document its use.

NOTE

It is legal to apply an annotation to itself. For example, the @Documented annotation is itself annotated as @Documented. Therefore, the Javadoc documentation for annotations shows whether they are documented.

The @Inherited meta-annotation applies only to annotations for classes. When a class has an inherited annotation, then all of its subclasses automatically have the same annotation. This makes it easy to create annotations that work in the same way as marker interfaces such as Serializable.

In fact, an annotation @Serializable would be more appropriate than the Serializable marker interfaces with no methods. A class is serializable because there is runtime support for reading and writing its fields, not because of any principles of object-oriented design. An annotation describes this fact better than does interface inheritance. Of course, the Serializable interface was created in JDK 1.1, long before annotations existed.

Suppose you define an inherited annotation @Persistent to indicate that objects of a class can be saved in a database. Then the subclasses of persistent classes are automatically annotated as persistent.

 @Inherited @Persistent { } @Persistent class Employee { . . . } class Manager extends Employee { . . . } // also @Persistent 

When the persistence mechanism searches for objects to store in the database, it will detect both Employee and Manager objects.