Waiting for Java 8: JSR-310, the threeten

For Java 7 the Fork/Join looked created, but I guess no one was eager to use it as Lambdas were still missing. Also interesting was the new filesystem API, which I’m yet to try out. I was really disappointed when JSR-310 was not included in Java 7. The current JDK time/date API’s are a shame. I thought to take a look at what’s the status of JSR-310.

Disclaimer: I’m not part of JSR-310 team and might be all wrong of everything below. Please comment on every bit of bad information!

At the moment JSR-310, the threeten seems to live at it’s sourceforge home. There’s a wiki where the current home page redirects to, also, the code is at github (nice).


I’m not really interested in any other than the current API. Coming from having had to bear with the prehistoric Java API, most notably java.util.Date, I thought to first take a look at Date’s new API.

Date still hasn’t lost it’s long-deprecated methods, but it now implements two new interfaces:

  • CalendricalAdjuster – does not really define any methods, just the root of calendrical objects interface hierarchy
  • CalendricalObject – support of extracting information and manipulating a copy of instance with CalendricalAdjusters

And a few new other methods:

Quick note: an Instant is a new version of Date, it represents an instant in time.

Looking further at the CalendricalObject it allows you to extract and manipulate. Extracting seems to resemble PostgreSQL’s EXTRACT except for the types of information you ask it to extract. Of the possibilities, I think that the Offset* types aren’t immediatedly clear.

Offset types

OffsetDateTime is basically a timezoned version of LocalDateTime. However, why do we have a OffsetDateTime if there’s a ZonedDateTime as well? The difference is that Offset* instances do not know from which timezone they are from, they just store the offset. This is visualized best by looking at the class itself consisting out of LocalDateTime and a ZoneOffset.


There seem to be two different notions of time periods – the time between two instants: Period and ISOPeriod. Apparently the first is simply amount of some calendar unit (for example days). ISOPeriod is more complex and seems to compensate for some ISO calendars like leap seconds? Not quite sure, at the verge of my calendar understanding here. Well, I guess all I need to know is that there’s a class for “5 years” and another one for – well, can’t figure out the use case, perhaps for the difference between instants?

The rest and status

Just browsing around the code it looks nice. Comment to code ratio is huge, however there’s some weird code as well, for example the StandardZoneRules -class – thought, I understand little of timezones themselves, so I guess these rules are clear for anyone with the appropriate knowledge. According to the main page of the javadocs, there are some really good practices like attempting to never return or accept nulls in place.

There have been quite the number of pull requests, infact 19, and there are 3 open at the moment, even one with Maven artifact output support.

On the issue side there seem to have been 42 closed issues and 53 open ones. A lot of discussion has been made in the issues, see for example the currently ongoing #85. Aside from github issue keeping there’s also a mailinglist with rather steady supply of messages, both interesting and in-depth about the usage. This really looks to become the most usable JDK API yet.

For an interesting “API stats” overview head over to Threeten API Stats and zoom down.

The threeten most certainly looks like project in good shape. I guess if those Maven jar’s got out in the central we could start seeing some real life adoption. Oh, that and a way to hook it up with the boot classloader without any work.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: