This tutorial starts by understanding deprecation and the reasons for deprecation in Java. We will then look at
@Deprecated annotation (
java.lang.Deprecated) which is used to mark an API’s program elements as deprecated. Next we take a quick look at which program elements can be annotated with
@Deprecated followed by a Java code snippet demonstrating
@Deprecated annotation’s use. We will then look at the
@deprecated Javadoc tag followed by a code snippet showing how
@deprecated Javadoc tag should be used.
What is deprecation – Deprecation of a program element in software engineering refers to discouraging the use of that element in new code being written. In Java, a compiler warning will inform the programmer against using deprecated APIs in their freshly written code.
Reasons for deprecation – Normally, deprecation in Java, or software engineering in general, is done due to one or more of the following reasons –
- A better, and recommended API, has been developed for use as an alternative to the deprecated one.
- A program element has been marked for removal due to some serious issues such as security. However, since a lot of existing code depends on the element being removed, hence instead of immediately removing the element, it will be marked as deprecated. This will give the existing consumers of the deprecated element valuable time to change their code accordingly.
- To bring in naming consistencies.
- To accommodate major design upgrade of the API libraries. With the fast changing technology landscape, API libraries evolve over time and slowly do away with older versions using deprecation technique.
java.lang.Deprecated annotation – Introduced in Java 5, or JavaSE 1.5,
@Deprecated annotation when applied on a program element gives a compiler warning when that element is used while coding. This compiler warning effectively dissuades or discourages a developer from using deprecated program elements which have been marked for removal in the forthcoming versions due to the reasons mentioned in the previous section of this article. Annotating with
@Deprecation is the ideal way for deprecating in Java.
Contexts in which an
@Deprecated annotation type is applicable –
@Deprecated annotation in Java can be used to annotate the following programming elements or constructs-
- Constructor declaration
- Field declaration (includes enum constants)
- Local variable declaration
- Method declaration
- Package declaration
- Formal parameter declaration
- Class, interface (including annotation type), or enum declaration
Example showing usage of
Have a quick look at the two classes below.
MainClass contains the
main() method in which it invokes deprecated method (
oldMethod()) and deprecated field(
DeprecatedExample class –
DeprecatedExample‘s deprecated method and field –
We then recompile with the Xlint command “javac -Xlint MainClass.java” –Notice the 2 detailed COMPILER WARNINGS shown above about using deprecated field and method.
@deprecated Javadoc tag – When a method is marked as deprecated using
@Deprecated annotation as described above, it is essential that the developer who is trying to use a deprecated element be given information regarding what to use as an alternative. Javadoc is the most ideal information to mention this information as Javadocs of an API are the main reference source for a developer using that API.
@deprecated Javadoc annotation has been specifically defined for deprecation related documentation.
Example showing how to use
@deprecated Javadoc tag Let us use the previous example of
DeprecatedExample class to see how
@deprecated Javadoc can be used –
@deprecatedJavadoc is used in the code above for specifying alternatives to both
Summary – In this tutorial we understood deprecation and for which reasons it is used. We then looked at
@Deprecated annotation, the program constructs it can be applied on and a code snippet showing
@Deprecated annotation’s use. Next we looked at how to add deprecation related information in Javadoc using
@deprecated Javadoc tag. Lastly, we saw a code snippet to understand how to use the
@deprecated Javadoc tag.