ISO8601 Java calendar system

The ISO 8601 calendar system is the default implementation within Joda-Time. The standard formalises the Gregorian calendar system used by the modern business world.

The ISO8601 standard was created by the International Organization for Standards based in Geneva. It aims to eliminate the risk of misinterpretting dates and times when representations are passed between systems and across national boundaries. We are unable to provide a direct link to the standard as it is a paid-for document. However some ISO8601 links may be useful.

The ISO8601 standard is based on the proleptic Gregorian calendar. This makes it fully compatible with the calendar system used in most countries today. The proleptic means that the Gregorian rules for leap years are applied for all time, thus the ISO8601 standard gives different results for dates before the year 1583 when the historic cutover from the Julian calendar occurred.

The standard sets out a framework within which dates and times can be represented. It offers many choices, however in reality there are three main date representations, year month day, year dayOfYear and year week dayOfWeek.

References

Month based

yyyy-mm-ddTHH:MM:SS.SSS
This is the most common format of ISO8601 and separates the fields by dashes. The fields are:

  • four digit year
  • two digit month, where 01 is Janurary and 12 is December
  • two digit day of month, from 01 to 31
  • two digit hour, from 00 to 23
  • two digit minute, from 00 to 59
  • two digit second, from 00 to 59
  • three decimal places for milliseconds if required
This format is used in XML standards for passing dates and times.

Day of Year based

yyyy-dddTHH:MM:SS.SSS
This format of ISO8601 has the following fields:

  • four digit year
  • three digit day of year, from 001 to 366
  • two digit hour, from 00 to 23
  • two digit minute, from 00 to 59
  • two digit second, from 00 to 59
  • three decimal places for milliseconds if required

Week based

yyyy-Www-dTHH:MM:SS.SSS
This format of ISO8601 has the following fields:

  • four digit weekyear, see rules below
  • two digit week of year, from 01 to 53
  • one digit day of week, from 1 to 7 where 1 is Monday and 7 is Sunday
  • two digit hour, from 00 to 23
  • two digit minute, from 00 to 59
  • two digit second, from 00 to 59
  • three decimal places for milliseconds if required
Weeks are always complete, and the first week of a year is the one that includes the first Thursday of the year. This definition can mean that the first week of a year starts in the previous year, and the last week finishes in the next year. The weekyear field is defined to refer to the year that owns the week, which may differ from the actual year.

Using ISO8601 in Joda-Time

Within Joda-Time the ISO8601 calendar system is the default. As such, all methods that take a chronology as a parameter will use the ISO chronology if null is passed in. There is almost always a version of the method without the chronology parameter, and this will default to ISO chronology.

The actual chronology class is ISOChronology. This is normally created if required using the factory method ISOChronology.getInstance(). 

// setup date object for midday on Christmas 2004 (default time zone)
DateTime dt = new DateTime(2004, 12, 25, 12, 0, 0, 0);

// or specify the chronology explicitly
Chronology chrono = ISOChronology.getInstance();
DateTime dt = new DateTime(2004, 12, 25, 12, 0, 0, 0, chrono);

// or use the default null handling behaviour
DateTime dt = new DateTime(2004, 12, 25, 12, 0, 0, 0, (Chronology) null);