Martin @ Blog

Dutch version can be found at the Finalist IT Group weblog.

Since the start of the development of JDK 7, there is quite some discussion on the API’s in the standard Java libraries which covers date and time. In the current Java version (1.6) there are roughly three major (groups of) classes which are responsible for handling date and time: Date and Calendar, the formatting classes, and the classes in the java.sql package, including java.sql.Date, java.sql.Time and java.sql.Timestamp. Most developers agree that these classes are far from perfect.

In order to resolve this issue, JSR-310 is started to improve the date and time API in the standard Java libraries. However, due to lack of developers and slow progress, it became very uncertain if the JSR would be ready for inclusion in JDK 7 (which will eventually become Java 7, the name I will use in the rest of this article). JSR-310 is lead by Stephan Colebourne and Michael Nascimento Santos. Colebourne is the original author of the increasingly popular Joda Time project, which is a replacement for the default Java date and time API’s. At Devoxx 2009, taking place last November, Mark Reinhold of Sun announced that Java 7 will be delayed until September 2010 at the earliest. Stephan Colebourne sees this as a opportunity to release at least a partially complete JSR-310 in time for the upcoming Java release.

But why is the current Java date and time API broken? How can you circumvent the issues in this API? And how does JSR-310 intends to resolve the issues in the upcoming release? These questions I will try to answer in this article.

Current date and time API in Java

While it is a bit to much to explain the complete workings of the date and time API in Java 1.6 (and before), I will try to explain the main problems with the current date and time API in Java. I assume some upfront knowledge of the API by the reader, but probably it is not very difficult to follow for people who don’t have extensive experience with the API.

The Java 1.6 standard library contains a few classes which deals with date and time. The most important ones are Date and Calendar. Almost the entire API is designed around these two classes. The main problem with them is that fairly simple operations on date and time require a rather large amount of code with many instances of individual classes. This has a negative impact on performance. The API is inconsistent and confusing for developers, making code using Date and Calendar hard to read and maintain. Additionally, the API is incomplete which force developers to create custom solutions for simple problems. Finally, the API misses opportunities which would made the usage of the API simpler. With this last point, I mainly refer to the lack of fluent API’s and the fact that all objects are mutable.

In the current API only a specific instance in time can be represented using a Date object. This object represents a specific point in time, internally defined by the number of milliseconds since the Epoch (January the 1st 1970 at 0:00 hour) and a timezone. In fact, this could be easily represented by an immutable object. Unfortunately, this is not the case. In earlier Java versions, many methods were added to the Date class making it possible to manipulate it. Nowadays, almost all these methods are deprecated and should not be used anymore. However, they still exists, and worse of all the setTime(long time) method is not deprecated and changes the state of a Date object.

The fact that Date is a mutable object, makes it hard to use it in other classes which are immutable. One should always make a defensive copy of every Date object that is part of an immutable object. Joshua Bloch gives an example in his book Effective Java:

public final class Period {
  private final Date start;
  private final Date end;
  
  public Period(Date start, Date end) {
    if (start.compareTo(end) > 0)
      throw new IllegalArgumentException(start + " after " + end);
    this.start = start;
    this.end = end;
  }
  
  public Date start() {
    return start;
  }
  
  public Date end() {
    return end;
  }
}

Objects of the type Period appears to be immutable, however it is not due to the usage of the Date class. An example where a Period object is changed:

Date start = new Date();
Date end = new Date();
Period p = new Period(start, end);
end.setYear(78); // Modifies internals of P!

This bug makes it possible to change the end date of the Period p, which renders the check in the constructor of Period void. Of course, there is a pretty simple way to prevent this problem by making a copy of start and end in the constructor of Period:

public period(Date start, Date end) {
  this.start = new Date(start.getTime());
  this.end = new Date(end.getTime());
  [...] // remainder omitted
}

However, this requires additional effort of the user of the API and can easily be forgotten. When Date objects would be immutable, this extra copy would not be necessary.

The other class in the date and time API in Java is the Calendar class. Instances of this class represents a point at a specific type of calendar (most of the time Gregorian) and provide methods to do some simple calculations. The main problem with this class is that it is mutable as well. The methods on this class are also not very beautiful. For example, to get the current year of the Calendar instance cal, one should call cal.get(YEAR) where YEAR is a constant. It is also confusing that a Calendar can operate in two modes, namely ‘lenient’ and ‘non-lenient’. In the first case, it is possible to define values for fields which are normally out of range. For example, it is possible to set the month to 15. The Calendar object then automatically converts it to a valid month, by increasing the year by one, and set the month to april.
Wait, april I wrote? Yes, months are zero-based in the Calendar (however, days, years, etc. are not).
The way the days of a week are represented are a little bit confusion

The main problems are clear now, however, there are many other smaller problems. For example, there also exists java.sql.Date, java.sql.Time and java.sql.Timestamp. These classes are childs of the java.util.Date class, but add some functionality for use in databases. However, there is a problem in the implementation of these classes. The java.sql.Date class and is used to represent a date without a time, while the java.sql.Time class represents a time without a date. Timestamp adds nanoseconds to the Date object. However, internally they still contain both a time and date and the implementers did not override the equals and hashCode methods causing hard to find bugs:

Date date = new Date();
Time time = new Time(date.getTime());
java.sql.Date sqldate = new java.sql.Date(date.getTime());
Timestamp timestamp = new Timestamp(date.getTime());

System.out.println(date.toString()); // Sun Dec 20 15:53:55 CET 2009
System.out.println(time.toString()); // 15:53:55
System.out.println(sqldate.toString()); // 2009-12-20
System.out.println(timestamp.equals(date)); // false
System.out.println(date.equals(timestamp)); // true

This means that java.sql.Timestamp does not obey to the equals contract, saying that the equals should be symmetric. Additionally, it is confusing that Time and java.sql.Date only represent a part of the date, but still use the same equals implementation.

There are more problems with the current API. For example, there is no way to define durations or a reliable way to represent a date without a time, or a time without a date. The performance of the API is unpredictable, because the fields are recalculated at unexpected moments. Finally, it is not very straightforward to format a date for print. One should use the (Simple)DateFormat classes for this, which means additional objects.

Joda Time

At this moment there is already a working solution for the problems described in the previous section. It’s called Joda Time and this is a replacement for the date and time API in the Java standard library. Joda Time solves most problems that currently exists. Joda Time contains two ways of defining a particular date or time: instant for a particular point in the ‘date time continuum’ and partial for a time or date representation which is not exactly a point in time, because a part is missing (the time, timezone, year, etc.).

Intstants in Joda Time are defined by the ReadableInstant interface, of which the most used implementation the DateTime class is. A DateTime object is immutable and contains a fluent API to do calculations on it (which of course return new objects). In order to make it easy to use it in existing projects, it is easy to convert a JDK Date object to a DateTime object and vice versa. Joda Time also provides a mutable version of the DateTime class, MutableDateTime, which can be used when a lot of transformation on a date has to be done. However, the usage of this object is most of the time not really necessary and should be avoided in my opinion. A MutableDateTime can easily be converted to a immutable version of it.

Partials are represented by the ReadablePartial interface, of which the most used implementations are LocalDate, LocalTime and LocalDateTime. Object of these types are also immutable and can easily be converted to DateTime objects and JDK Date objects. Additionally, Joda Time contains Duration, Period and Interval for completeness.

Of course, an example of Joda Time usage cannot be omitted in this article:

DateTime now = new DateTime();
Period sixdays = new Period(0, 0, 0, 6, 6, 0, 0, 0);
System.out.println(now); // 2009-12-20T18:35:53.360+01:00
DateTime future = now.plus(sixdays);
System.out.println(future); // 2009-12-27T00:41:59.097+01:00
System.out.println(now.withYear(2028).plusDays(31).toString("dd-MM-yyyy hh:mm")); // 20-01-2029 06:41

This example initializes now to the current time (the default value of a DateTime without constructor parameters). The variable sixdays contains a reference to a Period object which defines a period of 6 days and 6 hours. Periods can easily be added to a DateTime object using the plus() method. Note that the result of the method should be assigned to a variable, since it does not modify the existing object, but creates a new one which has to be assigned to a variable in order to use it actually.
The last line shows how easy it is to perform simple calculations with date using Joda Time. Additionally, it shows another feature of Joda Time, namely the ease to format a date according to a specific pattern. A similar operation would be much more difficult using the JDK Date and Calendar classes, since one would have to instanciate a Calendar, Date, SimpleDateFormat and call several individual methods.

Joda Time also makes many other use cases very simple. For example, the DateTime constructor accept many different types of objects for initialization. For example, one can provide many different formatted String objects, which are automatically parsed correctly. This includes the ISO 8601 format, which is used in XML. For testing purposes Joda Time also makes it possible to change the current time, using DateTimeUtils.setCurrentMillisFixed(millis);.

JSR-310 and Joda Time

As mentioned earlier, JSR-310 is lead by Stephan Colebourne, who also created Joda Time. It may be obvious to take the latest Joda Time release and put a JSR stamp on it, declaring it the reference implementation. This is not what is happening, with good reason.
Stephan devoted a recent blog post on this topic, explaining why JSR-310 differs from Joda Time. The main reason is that Joda Time is not perfect.
The design goals for JSR-310 are clearly defined: The API should support immutability, a fluent API, it has to be extensible and the API should be clear, explicit and expected. Especially this last point is where Joda Time is not perfect. For example, Joda Time uses the notion of Chronology to represent different calendar types. It is possible to define the Chronology when instantiating a DateTime object. In the default case, a DateTime object will return a value between 1 and 12 when calling the getMonthOfDay() method. However, when using a for examle a Coptic Chronology, this method can also return 13, since the Coptic calendar has 13 months. This makes the API return values the user might not expect, and in fact, the previous method call requires a check to make sure the result is as expected. Also the use of the ReadableInstant by DateTime and the Instant class (which is a machine representation of an instant in time) is wrong, since there is difference in how humans define an instant in time compared to how machines see it. Finally, Joda Time accept null values in many places without throwing an error, which is also wrong according to Colebourne.

The issues in Joda Time should be fixed in the JSR-310 implementation making it an even better date and time API. Should we therefor not use Joda Time? Definitely not! Of all available options, Joda Time is definitely the best choice for working with dates and times in Java. The fact that the completion of JSR-310 takes a very long time, is since for most developers Joda Time fixes the problem that exists in the current JDK API, making the urgency of completing JSR-310 pretty low.

Conclusion

The date and time function in the default Java SDK is flawed in many ways. While it can be used for most projects with some extra effort, it can also cause many unexpected problems. JSR-310 is on its way to finally fix this problem. However, it is still not yet sure if it will be part of Java 7, mainly because of the lack of developers.
For new projects, there is very few arguments for not using Joda Time. It is well tested and well supported, including support for Hibernate and JSP’s. It makes it a lot easier to perform calculations using dates, and provides an easy to use API with reliable performance.

Tags: Date Time API, Joda Time, JSR-310

This entry was posted on Wednesday, January 6th, 2010 at 12:48 and is filed under English, java, Software. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.