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 - [su_box title="DeprecatedExample.java and MainClass.java" style="soft" box_color="#fcba43" title_color="#00000" radius="4" Class="for-shortcodebox"][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 } }[/java][/su_box] We then compile the MainClass which uses DeprecatedExample's deprecated method and field - [su_note note_color="#000000" text_color="#FFFFFF"]C:\src>javac MainClass.java Note: MainClass.java uses or overrides a deprecated API. Note: Recompile with -Xlint:deprecation for details.[/su_note] We then recompile with the Xlint command "javac -Xlint MainClass.java" - [su_note note_color="#000000" text_color="#FFFFFF"]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[/su_note] 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 - [su_box title="Use of @deprecated Javadoc tag" style="soft" box_color="#fcba43" title_color="#00000" radius="4" Class="for-shortcodebox"][java]//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"); } }[/java][/su_box] 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.