Tuesday, 30 January 2007

Announcing JSR 310 - Date and Time API

For too long we've suffered the Date and Calendar APIs in Java. No more, I say, No more!

I am pleased to be able to announce JSR 310 - Date and Time API. Here's the summary of what the JSR is aiming for:

This JSR will provide a new and improved date and time API for Java. The main goal is to build upon the lessons learned from the first two APIs (Date and Calendar) in Java SE, providing a more advanced and comprehensive model for date and time manipulation.

The new API will be targeted at all applications needing a data model for dates and times. This model will go beyond classes to replace Date and Calendar, to include representations of date without time, time without date, durations and intervals. This will raise the quality of application code. For example, instead of using an int to store a duration, and javadoc to describe it as being a number of days, the date and time model will provide a class defining it unambiguously.

The new API will also tackle related date and time issues. These include formatting and parsing, taking into account the ISO8601 standard and its implementations, such as XML. In addition, the areas of serialization and persistence will be considered.

The final goal of the new API is to be simple to use. The API will need to contain some powerful features, but these must not be allowed to obscure the standard use cases. Part of being easy to use includes interaction with the existing Date and Calendar classes, something that will be a key focus of the Expert Group.

Obviously, this whole JSR will be influenced by Joda-Time, the open source library that I've been working on for the last few years. However, the JSR will not be a simple adoption of Joda-Time. For a start the Java 5 language features make a difference. And there are probably a few rough edges that can be smoothed out too. But overall, its a very solid base to begin from.

The JSR will be run by myself and Michael Nascimento Santos. I also want to thank our extensive list of supporters (19!) without whom we wouldn't have got to this point.

The aim in running the JSR is to be as open and transparent as possible. There will be a java.net project with a mailing list available for anyone to sign up to. We also aim to have a publicly readable Subversion repository. Joda-Time worked well as open-source - why shouldn't the JSR?

So, if you're interested in helping us move Java beyond Date and Calendar, then please consider joining the public mailing list or Expert Group (via JCP). Alternatively, feel free to leave comments here.


  1. Congratulations Stephen! its about "time" we had a decent collection of date/time utilities in the JDK.

  2. Hmm... looks like you're the right guy to give me a quick answer I'm seeking right in these days. A customer of mine has the need of representing dates:

    + including "precision" that can be limited only to part of the date (e.g. 17th century) or something like 14-15th sec
    + including dates before Christ - and a lot of time before such as 50.000 BC

    You get it, it's for date attributes of historic objects, events and such.

    As they are only in the western calendar, it's not really a hard task, basically all I need is to keep the order capability and to have some control in formatting / parsing. At the moment I'm thinking of just replacing Date with a double representation of time in days and "precision" field, but I'd be much happier if I'd find something already working and tested :-) I realize that there are wasp nests all around for what concerns testing, parsing, formatting, etc - even though not so important in the specific case, as the specs are not so complex. Is Joda-Time a right place to search for a comprehensive solution?

    Thanks in advance.

  3. Congratulations, Stephen! This was due for quite some time now. I love what you did with JodaTime, and I'm sure you'll do an excellent job on this JSR too.

  4. Stephen Colebourne30 January 2007 14:43

    @Fabrizio, The Partial object in Joda-Time can be setup to hold a century:
    ' new Partial(DateTimeFieldType.century(), 17);
    BC dates are not a problem.
    You would need your own structure of start and end to hold 14th-15th century at present.

    Whether its worth using Joda-Time for this probably depends on whether the other features such as formatting and parsing, and more robust dates in general, appeal to you.

  5. Thank you. At this point, I'd give Joda a try for sure. Not a problem about managing the ranges by hand, it's simple. BTW the project I'm leading *could* be opensourced (a final decision hasn't been taken yet, and I'm not in charge of it), in this case - if we use Joda - I hope to give some contribute back.

  6. Due to the 2007 US-DST changes we are having to force everyone to move onto newer JDK here at work, which caused massive headache. It would be good if the updating of timezone information is made easier. Looking at Joda-Time API it seems to me that it will required one to re-compile the classes - that's painful. I think while we are at it we should consider how to make the timezone update easier and more painless.

  7. Stephen Colebourne30 January 2007 15:27

    @Sunny, Updating the timezone info without compilation is a known issue that I want the expert group to evaluate. It is in fact possible to update Joda-Time without recompiling, however this is undocumented at present.

  8. This JSR is something I quite like a lot. The usability of current date handling is awful and one has to bend and stretch the code to do what one actually wants to do. I frequently trap over what starts counting at 0 and what doesn't. And only if I think about the terrible code one writes to identify times (comments required). Milliseconds might be nice sometimes, but not very handy.
    Especially the representation of many abstractions like hour, day, etc. as can be seen in joda.time will be of high use.
    Wishing you all the best with succeeding on this JSR.

  9. I created an alternate reality chronology using Joda-Time 1.0, where every month has exactly 28 days, starting on a Monday, giving a year length of 336 days. It would be nice if I could still create alternate reality chronologies using JSR 310.

  10. Stephen, a big congratulations on this. It seems an age since JavaPolis 2005, I hope it works out well for you, and in turn Java gets the Date/Time functionality it needs.

  11. Great news Stephen !! Date time api's in JDK are the worst of the lot. We have been using Joda date-time api for quite some time now .. feels like a charm ..

  12. Excellent news!

    I certainly hope this makes the target stated on JSR page of being included in Java SE 7. Being bundled with the platform would hopefully allow:

    * integration with JDBC

    * integration with MessageFormat (so that we don't need to switch between MessageFormat localization and Joda-Time localization, keeping the best of both).

    * integration with other APIs where possible, to maximize the benefits of Joda-Time's immutability.

    It'd be nice to see "native" integration at interpreter level of scripting languages such Groovy or the JDK-bundled JavaScript, or (dreaming now) javac-level integration of dates, just like string objects are recognized by literal format...

    - Chris

  13. Great news!!

    For the people interested... you can find a BeJUG JODA-time talk by Stephen @

  14. Benoit Xhenseval2 February 2007 15:37

    Excellent News,

    I suggest that some basic 'holidays' functionality is also added. The ability to say that a given date is a non working day, that a WorkingWeek may include Saturday but not Friday and the ability to calculate dayForward/backWard and co would be very useful.

    For those who cannot wait, we wrote the ObjectLabKit to fulfil these requirements


  15. I suggest have a function to get the length of time between two snapshot.

    Yes, we have currentTimeMillis. But it does INCORRECT when the system clock getting changed. e.g. NTP.

    And it cause problem when you getting zero or negative value.

  16. Please also consider including a function to query the hardware time (getCurrentMilliseconds is just not enough). High precision timing would be fantastic!