Is java.util.Date Deprecated?

by Paul Hill, August 2004

If you look at java.util.Date, you will find that most of it is deprecated. This makes you wonder if the intent is for Java programmers to use something else instead. You might guess that you should be using java.util.Calendar. This turns out to not be the case.

Looking at java.util.Dates we see that of its 6 constructors, only two are not deprecated. Of the 28 methods of the class, 8 are not deprecated, and of those, 5 override the standard methods of java.lang.Object -- toString(), hashCode(), clone(), compareTo(Object o) and equals(Object obj) -- one of the others is a simple variation of compareTo -- compareTo(Date anotherDate). All this leaves is getTime(), setTime(long time), Date() and Date(long date).

A Role for java.util.Date

It looks like nothing remains for java.util.Date to do. So should we leave it for dead and go on to other things? No, java.util.Date still has an important role. A java.util.Date is a value object. Another way to think about a java.util.Date is that it is a variation of the Memento or Token pattern. It simply holds state -- a value. It serves somewhat the same role java.lang.Integer; it's just a typed container.

It is worth noting that java.util.Date is not made up a series of fields representing year, month, day etc., but is a long integer value of milliseconds since 1970-01-01 00:00:00.00 GMT. This is a very compact way to represent a date and time value, thus fits the idea of the Memento pattern very well. Looking again at the remaining methods and constructors all we see are methods for creating Dates with a millisecond value and getting that millisecond value. Such a simple object is useful for passing around, which is why various methods in the API still take Date, not because they are as old as the Date class, but because they only need a simple date-time binary value.

Maybe the most common use of Date is in JDBC. The JDBC libraries represent dates (no time of day), timestamps (a timestamp possibly down to the nanoseconds) or time (just a time value) using subclasses of java.util.Date. The JDBC does not take or return Calendars in as object that holds a date-time or timestamp.

You should use a java.util.Date to hold timestamps when you need to move such values between different parts of your software.

A Role for java.util.Calendar and java.util.GregorianCalendar.

Given the argument above for java.util.Date, you might ask what then is the role of java.util.GregorianCalendar, the implemenation in standard libraries of the abstract class java.util.Calendar? GregorianCalendar is a variation of a strategy pattern "A strategy is an algorithm" 1. The GregorianCalendar is an algorithm for converting a moment in time to a particular year, month, day, hour, minute, second etc. In order to do this, the GregorianCalendar must know which timezone to use which will also include when the daylight savings begins. It might need to know such bits of arcane knowledge as when the older Julian calendar switched to the Gregorian calendar. GregorianCalendar also contains an array of values for holding all of the various fields it knows how calculate. All of this additional information as part of its extensive internal state, makes GregorianCalendar many tens of times larger than the much simplier java.util.Date.

Separating out the algorithm from the simple state allows us to replace one strategy with another. If you needed to calculate the year, month and day and year fields of another calendar you could use a different implementation of java.util.Calendar. There are various implementations of calendar available including ChineseCalendar, HebrewCalendar, and IslamicCalendar available from the IBM ICU4J Project.

What about SimpleDateFormat?

You might be thinking that the there is a third option, java.text.SimpleDateFormat. What you will find is that this class uses a java.util.Calendar just as it should use a strategy. Internally, SimpleDateFormat uses a Calendar for all date calculations. It is also true that when you call Date.toString(), you are also using a Calendar -- the default calendar -- to calculate date fields.


java.util.Date might look as if it is on its last legs and should be relegated to history, but it continues to have a vital role as a value object or memento which holds a date-time stamp. It should not be replaced with Calendar and its subclasses, but used in conjuntion with those classses.


[Memento] Memento Pattern;, 2004-08-26

[Strategy] Strategy Pattern;, 2004-08-26

[Value Object] Value Object;, 2004-08-26

[Werner] Werner, Laura; International Calendars in Java;, 2004-08-26

[ICU4J] International Components for Unicode for Java,, 2004-08-26

[JDBC] JDBCTM API Documentation;, 2004-08-26

The author can be reached at goodhill (AT)