Business and server-side applications have long since suffered from the buggy and confusing JDK Date and Calendar classes, and the thread-unsafe DateFormat. With the release of Joda-Time 1.0, you need suffer no more!

Joda-Time provides a Java library for date and time handling including the ISO8601 standard. It completely replaces the JDK Date and Calendar classes, while still providing good integration. It is open-source software under the ASF2 license.
 
The major 1.0 release has just been completed after more than a year of development, testing and beta releases. We consider Joda-Time ready for production use.

Homepage: http://joda-time.sourceforge.net
Download: http://sourceforge.net/project/showfiles.php?group_id=97367&package_id=104212


Major features of Joda-Time
- Easy to Use - Calendar makes accessing 'normal' dates difficult, due to the lack of simple methods. Joda-Time has straightforward field accessors. And the index of January is 1!

- Extensible - Joda-Time supports multiple calendar systems via a plugin mechanism, which is much more extensible than the subclasses of Calendar. Currently supported calendars are ISO8601, GregorianJulian, Buddhist (Thai) and Coptic.

- Comprehensive - Joda-Time includes classes for datetimes, dates without times, times without dates, intervals and time periods.

- Advanced formatting - A thread-safe advanced formatting mechanism is included. This is also extensible - by writing to an interface you can include some unusual piece of formatting in the middle of the text.

- Well documented. There is documentation in the form of a quick and full user guide, plus reference pages, FAQs and javadoc.

- Tested. There is good test coverage, see the website, providing an assurance of quality.


Feedback
As always, let us have any feedback - whether bugs or reviews, good or bad! In particular, we are seeking coders to help implement more calendar systems, such as the Hebrew, Islamic, Chinese and Japanese. Only with the input from the community can the library truly grow and improve.
 
Joda-Time team
http://joda-time.sourceforge.net

... and replace it with Joda-Time! :)

All in all, very nice work!

--
Z.

http://zoe.nu/

There is more than one mathematical model for time values:

1. value represents specific point in time, but different date and time in different time zones
2. value represents specific date and time, but different points of time in different time zones
3. value represents specific date and time in specific time zone
4. value represents specific point of time in specific time zone

Ask yourself what happens when you send message with a time value to different time zone.

java.util.Date is based on model 1, but in external storages, like databases, model 2 is mostly used. If you fetch same database record from New York and from London you will get Date values that are not equal. Even in the same time zone, if you fetch the record before and after DST changes, you are not sure are those values equal or is duration between 10pm today and 10pm tomorrow 24, 23 or 25 hours.

In MySQL database there are Timestamp and DataTime for model 1 and model 2.

Unfortunately, I see only model 1 based types in Joda-Time.

Nebojsa

Let me try to explain the Joda-Time classes, and link them to your descriptions:

- DateTime: holds long milliseconds (from 1970-01-01Z) and a DateTimeZone. The getXxx methods return date and time for the stored time zone. You can create a different DateTime object to see the fields in another time zone. You can compare two DateTime objects either with or without reference to the time zone. - This seems to correspond with your model 4 (and model 3?).

- Instant: As DateTime, but without the getXxx methods and with the time zone forced to UTC. This is a basic time zone and interpretation neutral datetime object. - Again this seems to correspond with your model 4.

- YearMonthDay: Holds int year, int month and int day. No time zone. This can be converted to a DateTime by adding a time zone (and optionally a time of day). - This corresponds to your model 2 (when combined with TimeOfDay class).


You may have interpretted Joda-Time as model 1 because the default constructor of a DateTime uses the time zone of your machine. However, internally it stores the zone in the object, thus passing the object (or a string version of the object that includes the zone) to another machine will correctly retain the time zone information.

YearMonthDay: Holds int year, int month and int day. No time zone. This can be converted to a DateTime by adding a time zone (and optionally a time of day). - This corresponds to your model 2 (when combined with TimeOfDay class).

OK, I may define YearMonthDayTimeOfDay class (or interface first). One possible iplementation is based on (YearMonthDay,DayTimeOfDay) pair as you sead. Other possible implementation is based on DateTime in GMT time zone.

Then I should implement methods for date/time calculations like adding duration/period, calculating diference etc (in GMT DateTime based implementation this is easy).

Then I shoud implemet YearMonthDayTimeOfDay(java.sql.Ttimestamp t) constructor (or static method) and toSqlTimestamp() method:

YearMonthDayTimeOfDay(t)
represents exactly same date and time as t.toString()

yearMonthDayTimeOfDay
represents exactly same date and time as
yearMonthDayTimeOfDay.toSqlTimestamp().toString()

At the and I should define custom type for my favorite O/R mapping fremewor (for instance Hibernate).

Do you cosider extending Joda-Time in this way.
You may have interpretted Joda-Time as model 1 because the default constructor of a DateTime uses the time zone of your machine. However, internally it stores the zone in the object, thus passing the object (or a string version of the object that includes the zone) to another machine will correctly retain the time zone information.
What are semantics of equals() and comareTo() metnods of DataTime? Semantics of those methos are millisecs OR YearMonthDayTimeOfDay based, not both.

But you are rigth, millisecs + timezone is match better then just millisecs.

Nebojsa

OK, I may define YearMonthDayTimeOfDay class (or interface first). One possible iplementation is based on (YearMonthDay,TimeOfDay) pair as you said.

We already have an interface - ReadablePartial - that is shared between YearMonthDay and DayTimeOfDay. If you do write a combined YearMonthDayTimeOfDay pair then it should implement the interface too. Simply extend the base class BasePartial.

We did consider including this in Joda-Time, and we also considered a LocalDateTime (more obvious name, implemented as milliseconds and no time zone). One of these two will probably get added. Please join the mailing list (http://sourceforge.net/mail/?group_id=47291) if you'd like to influence the decision, or contribute some code ;-)

As someone who makes heavy use of java.util.Date and java.util.Calendar, I'm excited to see what looks like (with a quick glance) a viable replacement!

Thanks for your efforts, and I'll definitely look into using your library to help with my project (http://www.opensymphony.com/quartz).

Great news! If we only had this a couple of years ago! Now too much code has been written with the old API. I wish this were integrated into the standard Java (Java 7.0? :-).

Congratulations, Stephen!

Good job.

Looks great.

How expensive is it to use (object creation, etc.) compared to the Calendar?

How is it compared to timeandmoney library?
http://timeandmoney.sourceforge.net

Joda-Time tackles a broader challenge than that of http://timeandmoney.sf.net.

Joda-Time has a full range of classes and implementations that completely replace Date and Calendar (while still providing interoperability).

TimeAndMoney provides a wrapper around the Calendar class.

Both approaches are valid for different circumstances, however, our opinion was, and is, that JDK calendar is soo broken, has so many odd performance glitches, has had and continues to have so many bugs, that a complete replacement was required.

Now don't have to write that tedious code for getting date from Calendar.
Thanks Stephen

I've just migrated our product to use JodaTime and what I've seen so far feels solid. Good work!

We mostly work with dates and times that are absolut, our system don't really care about timezones. That is up to a separate system to handle, when working with the data exported from our system. So far this seems easier to handle with JodaTime than the standard Java stuff.

One of the things I posted on the Mustang list is that rt.jar should be broekn up into mutiple jars.
Like all the corba stuff. This enables evolution.

Also Joda-Beans rock!
.V

Doesn't come with Hibernate persisters does it ;) Looks like it could save a *lot* of time for developers working with dates.

Doesn't come with Hibernate persisters does it ;) Looks like it could save a *lot* of time for developers working with dates.

No it doesn't, for two reasons:
1) None of the developers use Hibernate.
2) Hibernate is LGPL, and that has license implications (I don't want a license war in this thread...)

To solve the second, I'll need to setup a separate sourceforge joda-time-lgpl project.

To solve the first, we need some developers to help us write code and document how to get Joda-Time to work with Hibernate. Would you be interested in helping???

Sure, creating new types isn't difficult - need to discuss the licensing issue off line. It'd be excellent to be able to use the Joda-Time objects directly rather than converting between JDK objects and your objects each time. You can contact me at analogueboy at blueyonder dot co dot uk if you want some help on the hibernate integration.

Just ment as a start and surely not bugfree.

Here
http://l3x.net/imwiki/Wiki.jsp?page=Joda
you might find a Hibernate UserType for Jodas DateTime and a converter tag for JSF.

This allowed me to move away from javas Calendar.

If I need to just represent a date, would I use DateMidnight or YearMonthDay, or something else?
If I recall, there used to be a DateOnly class. Why was that removed?

Great job.

Nils

If I need to just represent a date, would I use DateMidnight or YearMonthDay, or something else?If I recall, there used to be a DateOnly class. Why was that removed?

DateOnly was removed because its semantics were broken (actually partly related to the model 1/2/3/4 discussion above).

The class was replaced with two that have different meanings:
- DateMidnight is a fully specified instant in the datetime continuum, with a time zone. It is defined as the milliseond instant at exactly mignight (00:00) at the start of a day. Thus it is similar to DateTime, but with a fixed time of midnight.

- YearMonthDay defines a day using the year, monthOfYear and dayOfMonth fields and no time zone. It can be thought of as a local date that covers the whole of the day from 00:00 to 23:59. Thus it could be considered to be a kind of interval.

If I were representing a birth date in my application (and didn't care about the time zone that the person was born in) then I would use YearMonthDay.

How the TimeZone information can be dynamically updated and tracked?
For example, the Brazil TZ DST start/end changes every year by government. And there is no rule for the change at all.

So I am looking for an impl of TZ that can keeps historical DST information and convert UTC to local time smartly based on that.

How the TimeZone information can be dynamically updated and tracked?For example, the Brazil TZ DST start/end changes every year by government. And there is no rule for the change at all.So I am looking for an impl of TZ that can keeps historical DST information and convert UTC to local time smartly based on that.

Joda-Time is perfect for this ;-)

The time zone information in Joda-Time is based on the public Olsen tz files of timezone information - http://www.twinsun.com/tz/tz-link.htm, as used by Unix and Java. However, with Joda-Time you can simply download the latest version of the files, compile them using ZoneInfoCompiler, and away you go!

And if that is not enough, you can create your own rules using the DateTimeZoneBuilder class. However, generally there is no need for this.

DateMidnight is a fully specified instant in the datetime continuum, with a time zone. It is defined as the milliseond instant at exactly mignight (00:00) at the start of a day. Thus it is similar to DateTime, but with a fixed time of midnight.

Two questions:
- What would be a use case for DateMidnight?
- What would be a use case for DateMidnight, that isn't easily applied using DateTime?

Just wondering if DateMidnight has an actual use case, or it's just a convienence class for a DateTime with the time being ... well ... midnight?

Two questions:
- What would be a use case for DateMidnight?
- What would be a use case for DateMidnight, that isn't easily applied using DateTime?
Just wondering if DateMidnight has an actual use case, or it's just a convienence class for a DateTime with the time being ... well ... midnight?

The use case is
a) anyone who wants a date only class with a time zone
b) anyone who has used Calendar in the past with time fields of zero to represent a date, and who wants to transfer to a semantically similar class.

Personally I believe that YearMonthDay is a better conceptual repesentation of a date only class. But Joda-Time tries to give some choices, see also MutableDateTime for anyone who doesn't like the immutable design pattern. If we didn't provide it I'm sure someone would ask for it!

Sounds great. Like most developers, I've endured the pain of DateFormat/Calendar etc and will definitely give Joda-Time a try on future projects.