JSR 310 Date and Time API for Java

| by Charles Humble Follow 904 Followers , Alex Blewitt Follow 4 Followers on Mar 17, 2010. Estimated reading time: 5 minutes |

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 mailing list, or comment directly on the Expert Draft Review wiki.

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Just now?? by Duraid Duraid

So until now java date and time types were mutable? hahahahhahaaaaa
(we're doing much better in .net)

API Refresh by David Sims

> JodaTime has been used by a lot of developers already,
> but it's time that the base Java case is improved for everyone.

We've used our fair share of the Java date and time APIs over the years. Although we, like most everyone, have been able to sort out the proper usages to manipulate times and dates as we would like, I'm looking forward to this API refresh.

David Sims
Flux Job Scheduler

Re: Just now?? by Hussachai Puripunpinyo

java.util.Date class was released in JDK1.0 (14 years ago)
The good side of java is it's highly backward compatibility
and it's the dark side too.

VB6 can be run in .NET virtual machine?

Re: Just now?? by Jacek Furmankiewicz

Go back where you came from...yes, exactly there. When you can run on my Linux cluster come back.

Re: Just now?? by Duraid Duraid

cluster, huh.. people are talking about the cloud man and you're still talking about a cluster.

Anyways.. this has nothing to do with platform wars but simple API design. I surprised how they designed a date type and made it mutable. Dates, numbers, zip codes are immutable didn't they know that?

Re: Just now?? by Rafiq Ahmed

True..... I am using java from last 5 year...

And I have never used it..well...Java is open ..and there is excellent data-time api that Apache provide... that's the one of small benefit (many more !!!) of using Open source.

Push for some usage? by Adrian A.

Maybe you should try to push for some usage of jsr-310 implementation among open source projects that need something like this, e.g. ORMs, calendar components, etc. (simply look at what projects would need it, and ask them to use it).
i.e. you need early adopters to get a real feedback from skilled developers.

Re: Just now?? by adrian collheart

>So until now java date and time types were mutable? hahahahhahaaaaa

Why are you laughing? We should all just be crying about this sad state of affairs.

>(we're doing much better in .net)

Yeah, lucky you. .NET has been a source for inspiration for Java, but this has been true the other way around too. I think both Java and .NET have fairly similar goals and take a similar approach to many things. Details differ of course.

Very few would argue that the current Date API in Java isn't an abomination, hence this new JSR ;)

Re: Just now?? by Werner Keil

Not only in the area of Date and Time.
F# has a consequent Units of Measure support, JSR-310 is lacking.

ICU4J, which aimed at fixing a couple of JDK problems earlier, has a more consistent model of measure, date, time and money.

Re: Just now?? by Werner Keil

Oh and it has a good concept of Holidays vs. Working Days. Something, e.g. the date and time libraries by CanadianMinds introduced that, as well as LocalTime:

Roedy Green developed some of these concepts as far back as 1996/7!.
He offered help to Sun/JavaSoft, but they turned his offer down. He and other experts quoted on his site should be in the EG, or at least heard by it.

Re: Push for some usage? by Florian Brunner

Yes, I would like to see some Swing and JavaFX date and time pickers and renderers based on this API.

What about mapping APIs such as JAXB (XML-Java), JPA (SQL-Java),...?

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

11 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you