How and When To Deprecate APIs
What "Deprecated" Means
You may have heard the term, "self-deprecating humor," or humorthat minimizes the speaker's importance. A deprecated class ormethod is like that. It is no longer important. It issounimportant, in fact, that you should no longer use it, since ithas been superseded and may cease to exist in the future.
Java provides a way to express deprecation because, as a classevolves, its API (application programming interface) inevitablychanges: methods are renamed for consistency, new and bettermethods are added, and fields change. But such changes introduce aproblem. You need to keep the old API around until developers makethe transition to the new one, but you don't want them to continueprogramming to the old API.
The ability todeprecate a class, method, or member fieldsolves the problem. Java supports two mechanisms for deprecation:and an annotation, (supported starting with J2SE 5.0) and a Javadoctag (supported since 1.1). Existing calls to the old API continueto work, but the annotation causes the compiler to issue a warningwhen it finds references to deprecated program elements. TheJavadoc tag and associated comments warn users against using thedeprecated item and tell them what to use instead.
When to Deprecate
When you design an API, carefully consider whether it supersedesan old API. If it does, and you wish to encourage developers (usersof the API) to migrate to the new API, then deprecate the old API.Valid reasons to deprecate an API include:
- It is insecure, buggy, or highly inefficient
- It is going away in a future release
- It encourages bad coding practices
Deprecation is a reasonable choice in all these cases because itpreserves "backward compatibility" while encouraging developers tochange to the new API. Also, the deprecation comments helpdevelopers decide when to move to the new API, and so shouldbriefly mention the technical reasons for deprecation.
It is not necessary to deprecate individual member fields(properties) of a deprecated class, unless of course you want toexplain a specific point about a property.
How to Deprecate
Starting with J2SE 5.0, you deprecate a class, method, or fieldby using the@Deprecated annotation. Additionally, youcan use the@deprecated Javadoc tag tell developerswhat to use instead.
Using the annotation causes the Java compiler to generatewarnings when the deprecated class, method, or field is used. Thecompiler suppresses deprecation warnings if a deprecated item isused within an entity which itself is deprecated or is used withinthe same outermost class or is used in an entity that is annotatedto suppress the warning.
You are strongly recommended to use the Javadoc@deprecated tag with appropriate comments explaininghow to use the new API. This ensures developers will have aworkable migration path from the old API to the new API. For moreinformation, seeUsing the@deprecated Javadoc Tag.
NOTE: The Java Language Specification requires compilersto issue warnings when classes, methods, or fields marked with the@Deprecated annotation are used. Compilers are notrequired by the Java Language Specification to issue warnings whenclasses, methods, or fields marked with the@deprecated Javadoc tag are accessed, although the Suncompilers currently do so. However, there is no guarantee that theSun compiler will always issue such warnings.
Using the @DeprecatedAnnotation
J2SE 5.0 introduces a new language feature calledannotations (also calledmetadata). One of the Java language's built-in annotations is the@Deprecated annotation. To use it, you simply precedethe class, method, or member declaration with "@Deprecated."
Using the@Deprecated annotation to deprecate aclass, method, or field ensures that all compilers will issuewarnings when code uses that program element. In contrast, there isno guarantee that all compilers will always issue warnings based onthe@deprecated Javadoc tag, though the Sun compilerscurrently do so. Other compilers may not issue such warnings. Thus,using the@Deprecated annotation to generate warningsis more portable that relying on the@deprecatedJavadoc tag.
In addition, the@Deprecated annotation causes thejavadoc-generated documentation to be marked "Deprecated" whereverthat program element appears.
NOTE: Deprecation applies to classes and to individualmethods or properties, not to their names. It is possible for asingle method to have deprecated and non-deprecated overloadings.It is possible for a non-deprecated property to hide or override adeprecated one, which removes deprecation. As developer of an API,it is your responsibility to deprecate overrides of a deprecatedmethod, if in fact they should be deprecated.
Example
The following is a simple example of using the @Deprecatedannotation fromjava.lang.Thread:
publicclass Thread implements Runnable {...@Deprecated public final void stop() { synchronized (this) {...Using the@deprecated Javadoc Tag
You can use the@deprecated tag to make Javadocshow a program element as deprecated. The@deprecatedtag must be followed by a space or newline. In the paragraphfollowing the@deprecated tag, explain why the itemhas been deprecated and suggest what to use instead.
Javadoc generates special HTML based on@deprecatedtags: it moves the paragraph following the@deprecatedtag to the front of the description, placing it in italics andpreceding it with a warning, "Note: foo is deprecated", in bold. Italso adds "Deprecated" in bold to any index entries mentioning thedeprecated entity.
The tagged paragraph can be empty, but empty deprecationparagraphs are bad form, because they do not help the user fix thewarnings that arise from the deprecation. Include paragraphs markedwith@link or@see tags that refer to thenew versions of the same functionality. It is usually not a goodidea to mention a timetable for phase-out of the deprecated API;this is a business decision that is best communicated otherways.
For more information on using the@deprecatedJavadoc tag, seeJavadoc - TheJava API Documentation Generator.
Example
The following examples show how to use the@deprecated Javadoc tag. They also illustrate the@Deprecated annotation, to emphasize that the twoshould be used together.
Here is an example of the most common form of a deprecatedmethod (for Javadoc 1.2 and later):
/** * @deprecated As of release 1.3, replaced by {@link #getPreferredSize()} */@Deprecated public Dimension preferredSize() {return getPreferredSize();}If the API reorganization was more than renaming, thedeprecation may be more complex. Here is an example of a methodthat is being retracted:
/** * Delete multiple items from the list. * * @deprecated Not for public use. * This method is expected to be retained only as a package * private method. Replaced by * {@link #remove(int)} and {@link #removeAll()} */@Deprecated public synchronized void delItems(int start, int end) {...}