|
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.
Regular AnnotationsThe @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-AnnotationsThe @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.
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.
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 annotationsIf an annotation is transient (such as @BugReport) or an implementation detail (such as @ActionListenerFor), then you should probably not document its use. NOTE
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. |
|