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.
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
- Calendrical Calculations - Millenium Edition - ISBN 0521777526
- Wikipedia - ISO Calendar
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
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
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);