Recipe 1.9 Dealing with Deprecation Warnings

Problem

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

Solution

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

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 the American Heritage Dictionary, to "express disapproval of; deplore." Java's developers are therefore disapproving of the old way of doing things. 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, 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 (if using Ant, use <javac deprecation= 'true '...>) 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.

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

You can also deprecate your own code. Put in a doc comment (see Recipe 23.2) with the @deprecated tag immediately before the class or method you wish to deprecate.