Monday 1 August 2011

Joda-Time v2.0

Joda-Time version 2.0 is now released! Download. Release notes.

Firstly, Joda-Time 2.0 is NOT a re-write of Joda-Time. The major version number change signifies that there are some incompatibilities. However, these are as minor as I could make them.

A few methods on Chronology that were deprecated for years have been removed, but most other deprecated and classes methods remain as the benefits of removing them were lower than the damage caused.

The library has moved to JDK 1.5 compatibility, adding generics. Sadly, adding generics to Comparable in some cases caused issues for implementations. The choice was to aim for binary incompatibility at the expense of source incompatibility if the ReadableInstant or ReadableDuration interfaces were implemented directly. If you didn't implement these, or extended the supplied abstract class then you should have no problems. Similarly, ReadablePartial had Comparable added, but if you didn't implement it, or extended the supplied abstract class then again you should have no problems.

In summary, I hope there are no significant binary incompatibilities. If you do find a binary incompatibility that I didn't, I'd like to know, particularly if it affects another open source project. If it is in the next week or so, then perhaps the incompatibilty can be fixed and "jar hell" avoided.

There are a number of semantic changes as well in the corner cases. Again see the release notes.

  • Parsing a month-day without a year now selects year 2000 rather than 1970 (so the 29th of February can be parsed)
  • Edge cases with a week-based-year and a month are handled better
  • Methods that handle daylight savings time (DST) are more consistent, retaining the offset wherever possible during calculations or consistently choosing summer time if not
  • Some short time zone IDs have been changed
  • DateTimeZone factory taking an ID is now case sensitive

And of course there are some enhancements:

  • Static factories now() and parse() added to the main date-time classes
  • New classes YearMonth and MonthDay
  • API added to plugin to the Joda-Time clock
  • Period formatting in multiple langauges
  • Parsing of LocalDate/LocalTime/LocalDateTime directly supported (much better than previously)
  • Parsing of time-zone IDs and some support for parsing time-zone names (via the builder)
  • Better handling of 'Z' when parsing to mean +00:00
  • Reliable way to get the start of day for a DateTime - withStartOfDay()
  • Convenient way to handle DST, DateTime.withEarlierOffsetAtOverlap() .withLaterOffsetAtOverlap()
  • Provide direct conversion from LocalDate and LocalDateTime to java.util.Date
  • More constructors and methods for Duration
  • More constructors for DateTime
  • Support JDK 1.6 pluggable resource providers
  • More compatible with the Java Memory Model in JDK 1.5 and higher
  • Added support for Joda-Convert without adding a dependency

Hopefully, you can just drop Joda-Time into your application and you will not notice any change. However, you should definitely read the release notes first.

Finally, as I'm sure someone will ask, this doesn't affect ThreeTen/JSR-310. This release was necessary to finally release a lot of bugs and enhancements in Joda-Time.

PS. As a bonus, there is a re-release of the JSP tags library, as apparantly it wasn't in maven central correctly up until now.

PPS. For Hibernate 4.0 support, please use the usertype project.


  1. Kris Nuttycombe1 August 2011 at 22:12

    A quick question: something that I frequently find useful in my projects is a "Clock" interface that acts as a factory for DateTime (and/or Instant) instances that can be mocked so that known dates can be used in testing scenarios. Is there anything like this in Joda-Time 2.0?

    Thanks a lot for joda-*!


  2. Stephen Colebourne1 August 2011 at 22:52

    The MillisProvider interface that acts as a clock is now public, although it has to be set as a static.

  3. Stephen, thank you very, very, very much for your great work :-)

    It's a pleasure to work with Joda-Time instead of the, well, strange standard API. I've introduced it to quite a number teams and/or projects in the past few years, and basically everyone was almost instantly convinced of its benefits. So please keep up your good work :-)

  4. Has anything been done to address first day of week. Before you give a big sigh, I believe this issue has forced a good number of people to not use Joda time. I see the at least initial intransigence to only use ISO as the rule for setting this value, there are other issues at play. Many businesses do not use Monday as the first day of the week, nor January 1rst as the first day of the year for that matter (financially in many jurisdictions businesses can set any day of the year as the first day of year). I also see this it possible some sort of anti-American sentiment such as, screw them those Americans always want to be different. Yet there are other countries that don't use Monday as the start of the week as well. Canada (although it may be officially, I don't know, in practice Monday is almost never considered the first day of the week and all calendars start on Sunday), Muslim countries, etc. I would like to see first day of week assignable. If you don't do it with Joda, at least do it with 310. Until then I and many others are forced to use the standard Java implementation. This frustrates me because in almost every other regard, Joda is so much better. Regards.

    1. Open Source is sometimes about scratching your own itch. I've never needed the day of the week as a number, so its never bothered me. Feel free to fork on GitHub and suggest an approach, perhaps as a variation in the formatter.

  5. Hi Stephen, I've been searching the internet (stack overflow and git hub mostly) trying to find an answer to a question I have about Joda-Time with no luck. My question is this: what does Joda-Time do in the case when there is no current rule in the tz database for a given date? Does Joda-Time have some default rules it uses? Does it just apply the last possible rule it finds for the given timezone? For example, the version of Joda-Time we are using uses IANA tz db 2012j. The last rules for Africa/Egypt are: Rule Egypt 2010 only - Sep 10 0:00 1:00 S, Rule Egypt 2010 only - Sep lastThu 23:00s 0 - However, now we are in 2017 and there are no rules past 2010. What does Joda-Time do? It seems to me that Joda-Time is applying the last known rules. Is that true? Sorry to bother you, thank you for your time!

    1. This would be better asked at Stack Overflow. Joda-Time just takes the last set of rules from tzdb and applies them to all future years. You can update the tzdb version yourself -


Please be aware that by commenting you provide consent to associate your selected profile with your comment. Long comments or those with excessive links may be deleted by Blogger (not me!). All spam will be deleted.