Java Doc for IslamicCalendar.java in  » Internationalization-Localization » icu4j » com » ibm » icu » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The Islamic calendar is strictly lunar, and thus an Islamic year of twelve lunar months does not correspond to the solar year used by most other calendar systems, including the Gregorian. An Islamic year is, on average, about 354 days long, so each successive Islamic year starts about 11 days earlier in the corresponding Gregorian year.

Each month of the calendar starts when the new moon's crescent is visible at sunset. However, in order to keep the time fields in this class synchronized with those of the other calendars and with local clock time, we treat days and months as beginning at midnight, roughly 6 hours after the corresponding sunset.

There are two main variants of the Islamic calendar in existence. The first is the civil calendar, which uses a fixed cycle of alternating 29- and 30-day months, with a leap day added to the last month of 11 out of every 30 years. This calendar is easily calculated and thus predictable in advance, so it is used as the civil calendar in a number of Arab countries. This is the default behavior of a newly-created IslamicCalendar object.

The Islamic religious calendar, however, is based on the observation of the crescent moon. It is thus affected by the position at which the observations are made, seasonal variations in the time of sunset, the eccentricities of the moon's orbit, and even the weather at the observation site. This makes it impossible to calculate in advance, and it causes the start of a month in the religious calendar to differ from the civil calendar by up to three days.

Using astronomical calculations for the position of the sun and moon, the moon's illumination, and other factors, it is possible to determine the start of a lunar month with a fairly high degree of certainty. However, these calculations are extremely complicated and thus slow, so most algorithms, including the one used here, are only approximations of the true astronical calculations. At present, the approximations used in this class are fairly simplistic; they will be improved in later versions of the code.

The IslamicCalendar.setCivil setCivil method determines which approach is used to determine the start of a month. By default, the fixed-cycle civil calendar is used. However, if setCivil(false) is called, an approximation of the true lunar calendar will be used.

This class should not be subclassed.

IslamicCalendar usually should be instantiated using com.ibm.icu.util.Calendar.getInstance(ULocale) passing in a ULocale with the tag "@calendar=islamic" or "@calendar=islamic-civil".

• ERA
• YEAR
• MONTH
• DAY_OF_MONTH
• DAY_OF_YEAR
• EXTENDED_YEAR