Java 1.5 Tiger A Developers Notebook [Electronic resources] نسخه متنی

6.3 Annotating a Deprecated Method

Like Override, java.lang.Deprecated is a marker annotation type. It also
has an analog in
the Javadoc world, the @deprecated tag. Both indicate
the same thing, although to different tools (see What about...).
Use Deprecated anytime you want to ensure that classes are
warned about overriding a particular method.

6.3.1 How do I do that?

Deprecated is a marker interface, and is used without parentheses or
member values, just as Override is. However, it is intended to be placed
on the same line as the declaration that is deprecated, where the
Override annotation was placed on the prior line. Example 6-2 is a simple
example of using Deprecated.

Example 6-2. Using the Deprecated annotation type

package com.oreilly.tiger.ch06;
public class DeprecatedClass {
/**
* This method has now been deprecated in favor of doSomethingElse( )
* @deprecated Use doSomethingElse( ) instead
*/
@Deprecated public void doSomething( ) {
// Really... do something...
}
public void doSomethingElse( ) {
// Do something else (and presumably better)
}
}

On its own, this annotation doesn't do anything. However, it comes into
play when other classes override deprecated methods, as the class in
Example 6-3 does.

Example 6-3. Overriding a method marked as deprecated

package com.oreilly.tiger.ch06;
public class DeprecatedTester extends DeprecatedClass {
public void doSomething( ) {
// Overrides a deprecated method
}
}

NOTE

Turn on deprecation
checking with
the "-Xlint:
deprecation" flag.

If you compile these classes, and turn on deprecation checking in your
compiler, you'll get a warning:

       [javac] src\ch06\DeprecatedTester.java:5: warning:
[deprecation] doSomething( ) in
com.oreilly.tiger.ch06.DeprecatedClass has been deprecated
[javac]   public void doSomething( ) {
[javac]               ^

Again, this isn't a revolutionary new feature, but it still adds some help
for introspection tools such as XDoclet.

6.3.2 What about...

NOTE

The Javadoc tag
is lower-case, the
annotation type is
uppercase.

...the @deprecated Javadoc tag? First, realize that it's not at all made
obsolete by the Deprecated annotation type. Javadoc comments are consumed
by the Javadoc tool, and are a vital part of any class's documentation.
The Deprecated annotation type is then used by the compiler to
ensure that your code matches what the documentation indicatesthat a
method or class is indeed deprecated. It's an important distinction, and
well worth remembering. In fact, you should always use the two in tandem,
one for documentation and one for compilation. Additionally, the
compiler will still read and process the @deprecated tag for backwards
compatibility.

In addition, you might wonder about the -deprecation flag, also available
to be passed to javac. If you compile with the -deprecation flag,
but without -Xlint:deprecation, you get the exact same result as using
-Xlint:deprecation. In fact, from what I can tell from testing the JDK,
these two flags function identically in Tiger.