Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News New Date and Time API Looks Set for Java 8

New Date and Time API Looks Set for Java 8

Leia em Português

This item in japanese

Lire ce contenu en français


Following refactoring work carried out over the summer to simplify and refine the API, JSR 310, the long running Java Specification Request led by Stephen Colebourne to replace Java's complex date APIs, has been added to the feature list for Java 8. It is expected to arrive in January 2013’s milestone 6 release.

Date handling is a complex problem, and in Java has a lengthy and less than glorious history. Initial support was via java.util.Date, a rather confusingly named numeric timestamp containing both a date and a time, which is not amenable to internationalisation. It has some other frustrating aspects too, such as using inconsistent offsets for properties, so that, for example, month and hours are zero based, day-of-the-month is one based, and year has an offset of 1900.

In 1997 Java 1.1 shipped, which added support for SQL via JDBC. This also had something called a date which inherited from java.util.Date, but had a different meaning. To add to the fun, in 1998 IBM contributed a replacement API, java.util.Calendar, which is amenable to internationalisation and offers considerable flexibility, but at the cost of a great deal of complexity even for relatively simple problems. Worse, all the properties in both java.util.Date and java.util.Calendar are mutable, so that, for example, any property of type Date (or of type Time or Timestamp) needs to be cloned when being returned from an accessor.

It wasn't until 2005 that Stephen Colebourne’s popular and widely-used Joda-Time library was released, improving the situation considerably, but requiring the use of an external library. JSR 310 builds on that experience, offering a replacement for both java.util.Date and java.util.Calendar in the Java SE standard library itself.

310 is a large API, but having used it a little I feel that it is consistent and easy to comprehend. In the latest version it deals with the complexity problem by offering a high level API primarily for use by applications, and a low level API for frameworks and other cases that may not be directly supported, so for example a developer could use the low level API to extend the supported set of date-time fields (YEAR, MONTH, DAY_OF_MONTH, HOUR and so on), to add a new field, such as "hour-of-fortnight".

The high level API provides a set of classes such as ZonedDateTime (for storing a date and time with a time-zone), LocalDate, LocalTime, and LocalDateTime for working with "human" dates and times, and Instant for a numeric timestamp useful for things like logging, analogous to Java.util.Date. All these classes are immutable and thread-safe.

With JSR 310 now set for inclusion in Java 8, the ThreeTen project has been established via OpenJDK to do the integration work. The project which provides the reference implementation for 310 is hosted on SourceForge with source code available on GitHub.

Java 8 itself is due for release in October 2013.

Rate this Article


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.

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

Community comments

  • New Date and Time API Looks Set for Java 8

    by Muhammad Khojaye,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Awesome. Nice to see that the datetime API's are at least being updating. This API alteast cover some features from Joda-Time Library, however, I still think that real live usage concept like Working or Non-Working day differences/calculation still better handle by other third party API's. Ali

  • Re: New Date and Time API Looks Set for Java 8

    by Javin Paul,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Indeed this is I guess most awaited feature in Java. With plenty of criticism of SimpleDateFormat and other Formatting class e.g. thread-safety issues, heavy weight, high serialization footprint. This is probably chance of Java team to wipe out all those sins and start a fresh and create good API for Java.

  • Better late than never

    by Giovanni Candido,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    This improvements is coming too late, but is the most waited. The Java Date API is much ugly and complicated, approaches like joda-time are much more powerful for date manipulation. But an standard API is very welcome because other frameworks like Hibernate and JPA can use the standard for data interchange. One common problem is when your application is layered, one technologic that is not compatible can make things harder. By Example the standard JSF converters for date and the joda-time api are not compatible, you have to write your own converter, but even if you do this, the primefaces calendar widget is not compatible with joda-time, because of the way they was written depends on the java.util.Date object.

  • Re: New Date and Time API Looks Set for Java 8

    by Charles Humble,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Agree a new binary distribution would be nice but it built easily enough from source for me using the provided Ant script - I just downloaded the .zip of Github and went from there.

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

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