Wednesday, 2 August 2006

Joda-Time 1.3 released

Well, it took a while, but the next release of Joda-Time is finally here. Version 1.3 includes two main enhancements in addition to the bug fixes:

Three new datetime classes have been added - LocalDate, LocalTime and LocalDateTime. These represent a date, time or datetime without a time zone. As such LocalDate is a direct replacement for YearMonthDay, whilst LocalTime replaces TimeOfDay. Neither of the replaced classes has been deprecated yet however, due to their widespread adoption.

The new Local* classes use a more standard and reliable implementation internally, and fix some weird external semantics of the older classes. For example, it was not possible to query the dayOfWeek on a YearMonthDay (because it only holds year, month and day!). LocalDate uses a different implementation, so that restriction no longer applies.

The second major enhancement is the addition of convenience methods to change each field value - immutable equivalent of set methods. Here is how to set the day to the first day of the month, constrasting before and after:

// previously
firstOfMonth = dt.dayOfMonth().setCopy(1);

// version 1.3
firstOfMonth = dt.withDayOfMonth(1);

Clearly, the new code is more readable and understandable. Note that as Joda-Time objects are immutable, the methods return a new instance with that field value changed. This is emphasised by the use of the verb 'with' rather than 'set'

As always, feedback is welcomed - whether bugs or reviews, good or bad! Only with input from the community can the library improve.


  1. Isn't 'immutable prefix' a better term for 'immutable verb' then?

  2. Hi,

    I'd always used DateMidnight instead of YearMonthDay... should I have been using YearMonthDay instead? (and hence LocalDate as of now?)

    - Chris

  3. Stephen Colebourne3 August 2006 10:43

    DateMidnight represents a date in a specific time zone. LocalDate (and YearMonthDay) represent a date without a time zone.

    For example, when considering birth dates, you rarely care what time zone the person was born in - only the date matters. hence you would use LocalDate.

  4. Thanks for that clarification. As it happens, I was just finishing off an article on my own blog about Joda-Time, so I've applied your advice (and the new objects). Hope the article's correct. :-)