What's wrong with Java Date & Time API?

Very often I come across negative feedback on Java Date and other date-time-related classes. Being a .NET developer, I cannot fully (without having used them) understand, what's actually wrong with them.

Can anybody shed some light on this?

Ah, the Java Date class. Perhaps one of the best examples of how not to do something in any language, anywhere. Where do I begin?

Reading the JavaDoc might lead one to think that the developers have actually got some good ideas. It goes on about the difference between UTC and GMT at length, despite the fact that the difference between the two is basically leap seconds (which happen pretty rarely).

However, the design decisions really lay to waste any thought of being a well designed API. Here are some of the favourite mistakes:

• Despite being designed in the last decade of the millennium, it rates years as two digits since 1900. There are literally millions of workarounds doing 1900+ (or 1900-) in the Java world as a result of this banal decision.
• Months are zero indexed, to cater for the spectacularly unusual case of having an array-of-months and not living with a thirteen element array, the first of which containing a null. As a result, we have 0..11 (and today being month 11 of the year 109). There are a similar number of ++ and -- on the months in order to convert to a string.
• They're mutable. As a result, any time you want to give a date back (say, as an instance structure) you need to return a clone of that date instead of the date object itself (since otherwise, people can mutate your structure).
• The Calendar, designed to 'fix' this, actually makes the same mistakes. They're still mutable.
• Date represents a DateTime, but in order to defer to those in SQL land, there's another subclass java.sql.Date, which represents a single day (though without a timezone associated with it).
• There are no TimeZones associated with a Date, and so ranges (such as a 'whole day') are often represented as a midnight-midnight (often in some arbitrary timezone)

Finally, it's worth noting that leap seconds generally correct themselves against a good system clock which is updated with ntp within an hour (see links above). The chance of a system being still up and running in the introduction of two leap seconds (every six months minimum, every few years practically) is pretty unlikely, especially considering the fact that you have to redeploy new versions of your code from time to time. Even using a dynamic language which regenerates classes or something like a WAR engine will pollute the class space and run out of permgen eventually.

JSR 310, which supplanted the old date-time classes with java.time in Java 8, justifies itself in the original JSR as follows:

> 2.5 What need of the Java community will be addressed by the proposed > specification? > > Currently Java SE has two separate > date and time APIs - java.util.Date > and java.util.Calendar. Both APIs are > consistently described as difficult to > use by Java developers on weblogs and > forums. Notably, both use a zero-index > for months, which is a cause of many > bugs. Calendar has also suffered from > many bugs and performance issues over > the years, primarily due to storing > its state in two different ways > internally. > > One classic bug (4639407) prevented > certain dates from being created in a > Calendar object. A sequence of code > could be written that could create a > date in some years but not in others, > having the effect of preventing some > users from entering their correct > birth dates. This was caused by the > Calendar class only allowing a > daylight savings time gain of one hour > in summer, when historically it was > plus 2 hours around the time of the > second world war. While this bug is > now fixed, if at some point in the > future a country chose to introduce a > daylight savings time gain of plus > three hours in summer, then the > Calendar class would again be broken. > > The current Java SE API also suffers > in multi-threaded environments. > Immutable classes are known to be > inherently thread-safe as their state > cannot change. However, both Date and > Calendar are mutable, which requires > programmers to consider cloning and > threading explicitly. In addition, the > lack of thread-safety in > DateTimeFormat is not widely known, > and has been the cause of many hard to > track down threading issues. > > As well as the problems with the > classes that Java SE has for datetime, > it has no classes for modelling other > concepts. Non-time-zone dates or > times, durations, periods and > intervals have no class representation > in Java SE. As a result, developers > frequently use an int to represent a > duration of time, with javadoc > specifying the unit. > > The lack of a comprehensive date and > time model also results in many common > operations being trickier than they > should be. For example, calculating > the number of days between two dates > is a particularly hard problem at > present. > > This JSR will tackle the problem of a > complete date and time model, > including dates and times (with and > without time zones), durations and > time periods, intervals, formatting > and parsing.

• Date instances are mutable, which is almost always inconvenient.
• They have a double nature. They represent both a timestamp and a calendar date. It turns out this is problematic when doing calculations on dates.
• The numeric representations of calendar data are counter-intuitive in many cases. For example: getMonth() is zero-based, getYear() is 1900-based (i.e., the year 2009 is represented as 109).
• They are missing a lot of functionality you expect from a Date class.

I feel for you... as a former .NET programmer, I asked the same questions, the time API in .NET (timespans, operator overloading) is very convenient.

First, to create a specific date, you use either a deprecated API, or:

Calendar c = Calendar.getInstance();
c.set(2000, 31, 12)

To subtract a day you do evil things like

Date firstDate = ...
Calendar c = Calendar.getInstance();
c.setTime(fistDate);
c.add(Calendar.DATE,-1);
Date dayAgo = c.getTime();

or worse

Date d = new Date();
Date d2 = new Date(d.getTime() - 1000*60*60*24);

To find out how much time passed between two dates (in days / weeks / months)... it gets even worse

However DateUtils from apache (org.apache.commons.lang.time.DateUtils) offer some convenient methods and I found myself using only them lately

As Brabster wrote, Joda Time is also a good external library, but apache seems more "common" than anything else...

I find Java's Date API usable, to be honest. Most of the issues I've seen and heard about relate to the verbosity, the need to involve multiple classes to do anything useful (Calendar, Date, DateFormat/SimpleDateFormat) and the lack of simple accessors like getDayOfWeek().

Joda Time is a well-respected alternative API in Java, and in the Why Joda Time section it gives some more arguments as to why it is a viable alternative that might be of interest.