Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

Annotations

Release 5.0 of the JDK introduced a metadata facility called annotations. Annotations provide data about a program that is not part of the program, such as naming the author of a piece of code or instructing the compiler to suppress specific errors. An annotation has no effect on how the code performs.

Annotations use the form @annotation and may be applied to a program's declarations: its classes, fields, methods, and so on. The annotation appears first and often (by convention) on its own line, and may include optional arguments:

@Author("MyName")
class myClass() { }

or

@SuppressWarnings("unchecked")
void MyMethod() { }

Defining your own annotation is an advanced technique that won't be described here, but there are three built-in annotations that every Java programmer should know: @Deprecated, @Override, and @SuppressWarnings. The following example illustrates all three annotation types, applied to methods:

import java.util.List;

class Food {}
class Hay extends Food {}
class Animal {
    Food getPreferredFood() {
        return null;
    }
    /**
     * @deprecated document why the method was deprecated
     */
    @Deprecated
    static void deprecatedMethod() { }
}
class Horse extends Animal {
    Horse() {
        return;
    }
    @Override 
    Hay getPreferredFood() {
        return new Hay();
    }
    @SuppressWarnings("deprecation")
    void useDeprecatedMethod() {
        Animal.deprecateMethod(); //deprecation warning - suppressed
    }
}

@Deprecated

The @Deprecated annotation indicates that the marked method should no longer be used. The compiler generates a warning whenever a program uses a deprecated method, class, or variable. When an element is deprecated, it should be documented using the corresponding @deprecated tag, as shown in the preceding example. Notice that the tag starts with a lowercase "d" and the annotation starts with an uppercase "D". In general, you should avoid using deprecated methods — consult the documentation to see what to use instead.

@Override

The @Override annotation informs the compiler that the element is meant to override an element declared in a superclass. In the preceding example, the override annotation is used to indicate that the getPreferredFood method in the Horse class overrides the same method in the Animal class. If a method marked with @Override fails to override a method in one of its superclasses, the compiler generates an error.

While it's not required to use this annotation when overriding a method, it can be useful to call the fact out explicitly, especially when the method returns a subtype of the return type of the overridden method. This practice, called covariant return types, is used in the previous example: Animal.getPreferredFood returns a Food instance. Horse.getPreferredFood (Horse is a subclass of Animal) returns an instance of Hay (a subclass of Food). For more information, see Overriding and Hiding Methods.

@SuppressWarnings

The @SuppressWarnings annotation tells the compiler to suppress specific warnings that it would otherwise generate. In the previous example, the useDeprecatedMethod calls a deprecated method of Animal. Normally, the compiler generates a warning but, in this case, it is suppressed.

Every compiler warning belongs to a category. The Java Language Specification lists two categories: "deprecation" and "unchecked". The "unchecked" warning can occur when interfacing with legacy code written before the advent of generics. To suppress more than one category of warnings, use the following syntax:

@SuppressWarnings({"unchecked", "deprecation"})

Consult your compiler's documentation for a complete list of supported warning categories.

The more advanced uses of annotations includes writing a program that can read a Java program and process its annotations. To facilitate this task, release 5.0 of the JDK includes an annotation processing tool, called apt. In the next release of the JDK (codename Mustang) the functionality of apt will be a standard part of the Java compiler. For more information, see Getting Started with the Annotation Processing Tool. For more information on the work-in-progress for Mustang, see the Language Model API and JSR 269: Pluggable Annotation Processing API.

Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

Copyright 1995-2005 Sun Microsystems, Inc. All rights reserved.