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.
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.
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.
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.
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.