Java Cookbook

Dealing with Deprecation Warnings

Problem

Your code used to compile cleanly, but now gives deprecation warnings.

Solution

You must have blinked :-). Either live with the warnings -- live dangerously -- or revise your code to eliminate the warnings.

Discussion

Each new release of Java includes a lot of powerful new functionality, but at a price: during the evolution of this new stuff, Java’s maintainers find some old stuff that wasn’t done right and shouldn’t be used anymore because they can’t really fix it. In building JDK 1.1, for example, they realized that the java.util.Date class had some serious limitations with regard to internationalization. Accordingly, many of the Date class methods and constructors are marked “deprecated.” To deprecate something means, according to my Concise Oxford Dictionary of Current English, to “express wish against or disapproval of.” Java’s developers are therefore expressing a wish that you no longer do things the old way. Try compiling this code:

import java.util.Date;

/** Demonstrate deprecation warning */
public class Deprec {

    public static void main(String[] av) {

        // Create a Date object for May 5, 1986
        // EXPECT DEPRECATION WARNING
        Date d = new Date(86, 04, 05);        // May 5, 1986
        System.out.println("Date is " + d);
    }
}

What happened? When I compile it on Java 2, I get this warning:

C:\javasrc>javac Deprec.java
Note: Deprec.java uses or overrides a deprecated API.  Recompile with 
"-deprecation" for details.
1 warning
C:\javasrc>

So, we follow orders. Recompile with -deprecation for details:

C:\javasrc>javac -deprecation Deprec.java
Deprec.java:10: warning: constructor Date(int,int,int) in class java.util.Date has 
been deprecated
                Date d = new Date(86, 04, 05);          // May 5, 1986
                         ^
1 warning

C:\javasrc>

The warning is simple: the Date constructor that takes three integer arguments has been deprecated. How do you fix it? The answer is, as in most questions of usage, to refer to the Javadoc documentation for the class. In Java 2, the introduction to the Date page says, in part:

The class Date represents a specific instant in time, with millisecond precision.

Prior to JDK 1.1, the class Date had two additional functions. It allowed the interpretation of dates as year, month, day, hour, minute, and second values. It also allowed the formatting and parsing of date strings. Unfortunately, the API for these functions was not amenable to internationalization. As of JDK 1.1, the Calendar class should be used to convert between dates and time fields and the DateFormat class should be used to format and parse date strings. The corresponding methods in Date are deprecated.

And more specifically, in the description of the three-integer constructor, it says:

Date(int year, int month, int date)

Deprecated. As of JDK version 1.1, replaced by Calendar.set(year + 1900, month, date) or GregorianCalendar(year + 1900, month, date).

As a general rule, when something has been deprecated, you should not use it in any new code and, when maintaining code, strive to eliminate the deprecation warnings. As we shall see in Section 2.2, there is already at least one example of a deprecation warning method that has altogether stopped working.

The main areas of deprecation warnings in the standard API are Date (as mentioned), the JDK 1.0 event handling, and some methods -- a few of them important -- in the Thread class.

You can also deprecate your own code. Just put a doc comment with the @deprecated tag immediately before the class or method you wish to deprecate. Using doc comments is described in Section 23.3.