What's wrong with Java Date & Time API?

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.