InfoQ Homepage News JSR 310 Date and Time API for Java

# JSR 310 Date and Time API for Java

This item in chinese

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.

Adoption
Style

## 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

• ##### Just now??

by Duraid Duraid /

• ##### Re: Just now??

by Hussachai Puripunpinyo /

• ##### Re: Just now??

by Jacek Furmankiewicz /

• ##### Re: Just now??

by Duraid Duraid /

• ##### Re: Just now??

by Rafiq Ahmed /

• ##### Re: Just now??

by adrian collheart /

• ##### Re: Just now??

by Werner Keil /

• ##### Re: Just now??

by Werner Keil /

• ##### API Refresh

by David Sims /

• ##### Push for some usage?

by Adrian A. /

• ##### Re: Push for some usage?

by Florian Brunner /

• ##### Just now??

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

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

• ##### API Refresh

by David Sims /

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

> 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
jobscheduler.com

• ##### Re: Just now??

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

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??

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

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

• ##### Re: Just now??

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

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 /

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

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. /

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

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 apache.org 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??

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

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

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 /

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

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 /

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

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:
mindprod.com/jgloss/calendar.html

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?

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

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

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

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.