Islamic calendar system

The Islamic, or Hijri, calendar system is a Lunar calendar used in many Muslim countries.

The Islamic calendar system is a lunar calendar based on observation. The observation aspect of the calendar means that a new month can only be declared based on human observations of the moon, something which can obviously vary and is unsuited to computer calculation.

Joda-Time implements the arithmetic Islamic calendar, which is an approximation of the actual calendar. There are 12 months, each of 29 or 30 days, making a year of 354 days, or 355 in a leap year. The days in the month alternate, with the first month having 30 days, the second 29 days and so on. In a leap year, the twelfth month has 30 days instead of the normal 29.

The definition of a leap year in the Islamic calendar varies. All agree on a 30 year cycle, however which years within the 30 are leap varies by the leap year pattern:

15-based 2, 5, 7, 10, 13, 15, 18, 21, 24, 26, 29
16-based 2, 5, 7, 10, 13, 16, 18, 21, 24, 26, 29
Indian 2, 5, 8, 10, 13, 16, 19, 21, 24, 27, 29
Habash al-Hasib 2, 5, 8, 11, 13, 16, 19, 21, 24, 27, 30

Joda-Time allows you to choose between these leap year patterns. The 16-based algorithm is the most commonly used, and is the default. Note that Microsoft uses the 15-based pattern, and calls it the 'Kuwaiti algorithm'.

The epoch of the calendar system is 0622-07-16 (Julian) which is therefore 0001-01-01 (Islamic). The current (and only implemented) era is 'AH' (Anno Hegirae).

Days of the week are named 'the first day', 'the second day' and so on, where Sunday is the first day. The day of the week value (numeric) returned by Joda-Time however, is the same as the ISO day of week definition. Thus Sunday will return the numeric value 7, and Monday will return the numeric value 1.

A day in the Islamic calendar begins at sunset on the previous 'day'. Joda-Time does not model this, thus times and date rollover follow standard ISO definitions, in other words starting at midnight.

References

Using Islamic chronology in Joda-Time

Within Joda-Time the Islamic calendar system can be used by obtaining an instance of IslamicChronology. This is normally created via the IslamicChronology.getInstance() factory. The chronology is then passed into the constructors of the main date and time classes. 

// setup date object for midday on May Day 2004 (ISO year 2004)
DateTime dtISO = new DateTime(2004, 5, 1, 12, 0, 0, 0);

// find out what the same instant is using the Islamic Chronology
DateTime dtIslamic = dtISO.withChronology(IslamicChronology.getInstance());