Joda Time - Java date and time API

Joda-Time provides a quality replacement for the Java date and time classes. The design allows for multiple calendar systems, while still providing a simple API. The 'default' calendar is the ISO8601 standard which is used by XML. The Gregorian, Julian, Buddhist, Coptic and Ethiopic systems are also included, and we welcome further additions. Supporting classes include time zone, duration, format and parsing.

As a flavour of Joda-Time, here's some example code:

public boolean isRentalOverdue(DateTime datetimeRented) {
  Period rentalPeriod = Period.days(2);
  return datetimeRented.plus(rentalPeriod).isBeforeNow()
}
public boolean isJoinedInLastThreeMonths(DateTime datetimeJoined) {
  Interval last3Months = new Interval(Period.months(3), new DateTime());
  return last3Months.contains(datetimeJoined);
}
public String getBirthMonthText(YearMonthDay dateOfBirth) {
  return dateOfBirth.monthOfYear().getAsText(Locale.ENGLISH);
}

Why Joda Time?

Joda-Time has been created to radically change date and time handling is Java. The JDK classes Date and Calendar are very badly designed, have had numerous bugs and have odd performance effects. Here are some of our reasons for developing and using Joda-Time:

• Easy to Use. Calendar makes accessing 'normal' dates difficult, due to the lack of simple methods. Joda-Time has straightforward field accessors.
• Easy to Extend. The JDK supports multiple calendar systems via subclasses of Calendar. This is clunky, and in practice it is very difficult to write another calendar system. Joda-Time supports multiple calendar systems via a pluggable system based on the Chronology class.
• Comprehensive Feature Set. The library is intended to provide all the functionality that is required for date-time calculations. It already provides out-of-the-box features, such as support for oddball date formats, which are difficult to replicate with the JDK.
• Up-to-date Time Zone calculations. The timezone implementation is based on the public tz database, which is updated several times a year. New Joda-Time releases incorporate all changes made to this database. Should the changes be needed earlier, manually updating and building Joda-Time is easy.
• Calendar support. The library currently provides 8 calendar systems. More will be added in the future.
• Easy interoperability. The library internally uses a millisecond instant which is identical to the JDK and similar to other common time representations. This makes interoperability easy, and Joda-Time comes with out-of-the-box JDK interoperability.
• Better Performance Characteristics. Calendar has strange performance characteristics as it recalculates fields at unexpected moments. Joda-Time does only the minimal calculation for the field that is being accessed.
• Good Test Coverage. Joda-Time has a comprehensive set of developer tests, providing assurance of the library's quality.
• Complete Documentation. There is a full User Guide which provides an overview and covers common usage scenarios. The javadoc is extremely detailed and covers most of the API.
• Maturity. The library has been under active development since 2002. Although it continues to be improved with the addition of new features and bug-fixes, it is a mature and reliable code base.
• Open Source. Joda-Time is licenced under the business friendly Apache License Version 2.0.

Documentation

Various documentation is available:

• Two user guides - quick and full
• The key concepts and chronology documents in the left navigation area
• The javadoc for the current release
• The javadoc for the latest in development
• A FAQ list
• Information on downloading and installing Joda-Time
• The Subversion repository

Releases

Release 1.2.1 is the current latest release. This release is considered stable and worthy of the 1.x tag. It has extensive testing suites and has been used in production. We now recommend JDK 1.3 or later, and have performed no testing on earlier JDKs.

We will support the 1.x product line using standard Java mechanisms. The main public API will remain backwards compatible for both source and binary. The version number will change to 2.0 to indicate a change in compatibility.

Support

For support on bugs, using the library or to volunteer please contact the mailing list (or email direct to the list via joda-interest@lists.sourceforge.net).

Alternatively, you can contact the project lead, Stephen Colebourne via scolebourne@users.sourceforge.net.