Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

Annotations

Introduced in J2SE 5.0, annotations provide a way for programmers to instruct the compiler on how to handle certain situations. For example, an annotation can indicate that a particular method or class should be overridden in a subclass or that certain compiler error messages shouldn't be printed. Defining your own annotation is an advanced technique that won't be described here, but there are three useful annotations built-in to release 5.0 that will be discussed.

Annotations use the form @annotation and can be applied to methods or classes. For example:

@Override class Cat extends Pet {
}

or

@Override void feedTheDog() { }

The following example illustrates all three built-in annotation types, using methods:

import java.util.List;

class Food {}
class Hay extends Food {}
class Animal {
    Food getPreferredFood() {
        return null;
    }
    @Deprecated
    static void deprecatedMethod() {
    }
}
class Horse extends Animal {
    Horse() {
        return;
    }
    @Override //compiler error if getPreferredFood
              //overloaded, not overridden
    //Notice the return type is different
    //(covariant return type).
    Hay getPreferredFood() {
        return new Hay();
    }
    @SuppressWarnings({"deprecation", "unchecked"})
    void useDeprecatedMethod(List raw) {
        //deprecation warning - suppressed
        Animal.deprecateMethod();
        //unchecked warning - suppressed
        raw.add(new Horse());
    }
}

• java.lang.Override
  The @Override annotation indicates that a method defined in the current class must override a method is one of its superclasses. In the preceding example, the override annotation is used to indicate that the getPreferredFood method in the Horse class is overriding the getPreferredFood method in the Animal class. Note that this method is returning a different type (Hay) than the superclass (Food) — this practice is called covariant return types. For more information, see Overriding and Hiding Methods.

  If a method marked with @Override does not override the same method in one of its superclasses, the compiler will generate an error message.

• java.lang.Deprecated
  The @Deprecated annotation indicates that the marked method should no longer be used.

  ---

  Note: The @deprecated tag used by the Javadoc^TM tool achieves the same result as @Deprecation. As of J2SE 5.0, the compiler-based @Deprecation annotation replaces the Javadoc @deprecation tag.

  ---

  In the preceding example, the deprecatedMethod in the Animal class is marked with the deprecated annotation. Invoking or overriding the deprecatedMethod method will generate a compile-time warning, unless that warning is suppressed in the subclass.

• java.lang.SuppressWarnings
  The @SuppressWarnings annotation indicates that the named compiler warnings should be suppressed.

  ---

  Note: This annotation can be used as of release 5.0 and some Java compiler implementations may suppress compiler warnings, but this feature won't be fully implemented in javac until release 6.0.

  ---

  In the preceding example, the useDeprecatedMethod method in the Horse class uses the suppress warnings annotation to suppress both the unchecked and deprecation warnings that would otherwise occur.

For more information on annotations, see JSR 175: A Metadata Facility for the Java Programming Language. It is strongly recommended that you suppressed warnings only where necessary. For example, using the SuppressWarnings annotation on the entire Horse class is not recommended because genuine errors in the code might be hidden.

For more information on annotations, see the 5.0 Release Notes.

[PENDING: Is there any other place I can send them to for information on annotations?]

Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

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