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 at 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. :-)


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.