Deprecation in Java, @Deprecated annotation and Javadoc tag tutorial with examples

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.

@Deprecated or 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 @Deprecated annotation Have a quick look at the two classes below. MainClass contains the main() method in which it invokes deprecated method (oldMethod()) and deprecated field(oldField()) of DeprecatedExample class -

DeprecatedExample.java and MainClass.java

//DeprecatedExample.java
class DeprecatedExample {
 @Deprecated
 String oldField;
 
 String newField;
 
 @Deprecated
 public void oldMethod(){
  System.out.println("Deprecated method invoked");
 }
 public void newMethod() {
  System.out.println("Non-depricate alternative invoked");
 }
}
//MainClass.java
public class MainClass {
 public static void main(String args[]){
  DeprecatedExample exObj=new DeprecatedExample();
  System.out.println(exObj.oldField);//deprecated field
  exObj.oldMethod();//deprecated method
 }
}

We then compile the MainClass which uses DeprecatedExample's deprecated method and field -

C:\src>javac MainClass.java
Note: MainClass.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

We then recompile with the Xlint command "javac -Xlint MainClass.java" -

C:\src>javac -Xlint MainClass.java
MainClass.java:4: warning: [deprecation] oldField in DeprecatedExample has been deprecated
  System.out.println(exObj.oldField);//deprecated field
                          ^
MainClass.java:5: warning: [deprecation] oldMethod() in DeprecatedExample has been deprecated
  exObj.oldMethod();//deprecated method
       ^
2 warnings

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 -

Use of @deprecated Javadoc tag

//DeprecatedExample.java
class DeprecatedExample {
/**
* @deprecated As of release 4, replaced by newField
*/
@Deprecated
String oldField;

String newField;

/**
* @deprecated As of release 4, replaced by newMethod()
*/
@Deprecated
public void oldMethod() {
  System.out.println("Deprecated method invoked");
}

public void newMethod() {
  System.out.println("Non-deprecated method invoked");
}
}

The @deprecated Javadoc is used in the code above for specifying alternatives to both oldField and oldMethod().
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.

Click on a category to view all articles