When developing APIs which are publicly used by others, sometimes we have to replace the old APIs with newer, better and more efficient ones. A typical example is changing a method name to a new one which is more accurate or reflects more appropriate programming practices. In such case, we should keep the old method for backward compatibility with the existing users, whilst encourage them to use the alternate version in the Javadoc. This is referred as API deprecation.

Since Java 1.5, programmers can use the @Deprecated annotation type to mark a program’s element (class, method, field and constructor) deprecated. The following are some examples.

 

Java @Deprecated Examples:

• Deprecating a type (class or interface): Deprecated interface:

  @Deprecated
  interface Kool {
  	// interface methods
  } 

  Deprecated class:

  @Deprecated
  class Foo {
  
  	// class implementation
  
  } 

• Deprecating a method:
  

  class Bar {
  	@Deprecated
  	public void doSomethingWeird() {
  		// old method
  	}
  
  	public void doSomethingCool() {
  		// new, alternate method
  	}
  } 

• Deprecating a member variable (field):
  

  class Constant {
  	@Deprecated
  	public static final int MAX_SIZE 			= 1024;
  
  	// new, alternate field
  	public static final int MAX_UPLOAD_SIZE 	= 1024;
  
  } 

• Deprecating a constructor:
  

  class Car {
  
  	@Deprecated
  	Car(String color, int length, int width) {
  
  	}
  
  	// new, alternate constructor
  	Car(Style style) {
  
  	}
  } 

 

Some Rules about @Deprecated annotation:

• When a type, method, field or constructor is annotated with the @Deprecated annotation, the compiler will issue a deprecation warning if the deprecated element is used (e.g. invoked, referenced, or overridden). For example, if we call the doSomethingWeird()of the Barclass above like this:
  

  Bar b = new Bar();
  b.doSomethingWeird();

  
  The compiler will complain like this:
  

  Note: Path\to\java\file.java uses or overrides a deprecated API.
  Note: Recompile with -Xlint:deprecation for details.

   
• The compiler won’t issue a deprecation warning if:
  • The deprecated element is also used in another deprecated element, e.g. a deprecated class invokes a deprecated method.
  • The deprecated element is used within an entity which is annotated by the @SuppressWarnings(“deprecation”) annotation.
  • The deprecated element is declared and used both within the same outermost class. For example:
    

    class MyCollection {
    	@Deprecated
    	public static final int DEFAULT_CAPACITY = 10;
    
    	private int initialCapacity = DEFAULT_CAPACITY;
    
    } 

• The @Deprecated annotation has no effect on local variable or parameter declaration.

 

Notes:

When using deprecation, it’s a good practice to provide reason for the deprecation and/or recommend alternative solution in the Javadoc of the deprecated element. For example, the following is Javadoc of a deprecated method of String class:

void getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin)

Deprecated. 

This method does not properly convert characters into bytes. As of JDK 1.1, the preferred way to do this is via the getBytes() method, which uses the platform's default charset.

 

Reference:  How and When To Deprecate APIs

 

Other Annotations in Core Java:

• Java @Override annotation examples
• Java @SuppressWarnings annotation examples

 

Recommended Java Tutorials:

• 12 Rules and Examples About Inheritance in Java
• 12 Rules of Overriding in Java You Should Know
• 10 Java Core Best Practices Every Java Programmer Should Know
• Understanding Object Ordering in Java with Comparable and Comparator
• Understanding equals() and hashCode() in Java