JSR 310 Date and Time API for Java

Stephen Colebourne, lead of the JSR 310 Date and Time API, has recently published an Early Draft Review of the proposed additions and changes to the Java language. InfoQ caught up with Stephen at QCon London to find out more about the project.

InfoQ: Why do we need a new Date and Time API? What's wrong with the existing one?

Stephen: The main problem with the current APIs (java.util.Date and java.util.Calendar) is that they are mutable. In other words, consider:

public class Employee {
  private final Date startDate;
  public Employee(Date date) {
    startDate = date;
  }
  public Date getDate() {
    return startDate;
  }
}

Even though startDate is marked final, the returned java.util.Date instance is mutable, and so it's possible to externally mutate the employee's start date by calling setYear(). There are a number of other minor issues, such as years being indexed from 1900 and months from 0, but the key problem is mutability. And that's something that can't be fixed in place.

InfoQ: What's the equivalent of java.util.Date in JSR 310?

Stephen: There's actually two concepts of dates in JSR 310. The first is Instant, which corresponds roughly to the Java java.util.Date class, in that it represents a fixed point in time as an offset from the standard Java epoch (1st Jan 1970). Unlike the java.util.Date class, this has nanosecond precision.

The second corresponds to human concepts, like LocalDate and LocalTime. These represent the general time-zone less concept of a day (without a time component) or time (without a day component), similar to java.sql's representations. Another example is MonthDay which could store someone's birthday without a year. Each of these classes sores the correct data internally, rather than the classic hack of java.util.Date where midnight is used for for dates and 1970-01-01 is used for times.

InfoQ: You mentioned the thorny concept of time zones. What does this new API deliver in this regard?

Stephen: The first thing to separate is the difference between a time zone (like Europe/Paris or America/New_York) and the offset from UTC, like +01:00 and -08:00. An offset is simply the difference between UTC and local time, whereas the time zone is a named set of rules describing how the offset changes over time. For example, the time zone will describe that a specific region, such as New York, will have one offset at a given instant, and another offset a moment later (creating a gap or overlap on the local time-line, such as the Spring or Autumn Summer-time change).

There are three levels of class to support these concepts. LocalDateTime allow times to be represented without an offset or time zone. OffsetDateTime additionally specifies the offset while ZonedDateTime adds the time zone rules. In the past, many applications have tended to use time zones when all they really needed was offsets (which are much simpler, faster and less error prone). An example of this is the XML Schema specification which only supports offsets and not time zones. With JSR 310 this difference can be expressed.

Lastly, timezones rules change over time. Just before the Millennium, some countries changed from behind to ahead of the International Date Line; and Summer times can vary over time. For example, the United States recently brought back the start of their Summer time, so now it's Summer time in the United States but not Summer time in Europe. Then, there's some which change almost every year, like Brazil. The JSR 310 API allows for time zones to be versioned, and subsequently replaced, with newer versions of time zone data. Although the replacement is left for specific implementations, it would be possible for an organisation to drop in new rules to an existing VM by simply prepending the classpath with the new data, rather than having to update the entire JVM installation.

InfoQ: What about ranges between a start and end time?

Stephen: It's possible to represent a range between any two Instants using a Duration. For most code that currently uses a start and end date, this is the closest comparison.

As noted earlier, there are some specific concepts to represent YearMonth and MonthDay, which should be used when appropriate. There's also a Period which can be used to represent any period of time, like “two years, three months, seven days, four hours, fifty mintues”.

InfoQ: What about other calendars?

Stephen: The core calendar is the ISOChronology calendar, which is the default and used to map time like the GregorianCalendar does in the Java APIs at the moment. However, there is also support for a number of other chronologies, like CopticChronology and ThaiBuddhistChronology, with the ability to add others as required.

InfoQ: Some of these concepts have already been explored in JodaTime. What's the relationship between that and JSR 310?

Stephen: JodaTime has been used by a lot of developers already, but it's time that the base Java case is improved for everyone. The most obvious change is the package name (from org.joda.time to javax.time), but in practice there are a few subtle differences as well.

Firstly, null was accepted by a number of the Joda Time APIs to refer to 0 time or duration. Although tempting, this can result in a number of subtle errors (where a value isn't returned properly). JSR 310 fixes this by throwing an exception for null arguments.

Secondly, the distinction between computer-related times (Instant) and human-related times (DateTime) have been made more apparent. A parent interface InstantProvider replaces the previous ReadableInstant as a way of converting any time to an Instant.

Thirdly, all exceptions thrown are now subtypes of CalendricalExcpetion. Although a RuntimeException, this is a parent class which can be caught by clients of the library calls.

InfoQ: Finally, what's the current status of JSR 310?

Stephen: The JSR 310 expert group operates an open mailing list, and the early draft review was published three weeks ago. The end of the review period is the 28th March 2010; so if you have any comments on the piece, please direct them to the dev@jsr-310.dev.java.net mailing list, or comment directly on the Expert Draft Review wiki.