com.ibm.icu.util

Class IslamicCalendar

public class IslamicCalendar extends Calendar

IslamicCalendar is a subclass of Calendar that that implements the Islamic civil and religious calendars. It is used as the civil calendar in most of the Arab world and the liturgical calendar of the Islamic faith worldwide. This calendar is also known as the "Hijri" calendar, since it starts at the time of Mohammed's emigration (or "hijra") to Medinah on Thursday, July 15, 622 AD (Julian).

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 {@link #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 {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a ULocale with the tag "@calendar=islamic" or "@calendar=islamic-civil".

Author: Laura Werner Alan Liu

See Also: GregorianCalendar

UNKNOWN: ICU 2.8

Field Summary
static intDHU_AL_HIJJAH
Constant for Dhu al-Hijjah, the 12th month of the Islamic year.
static intDHU_AL_QIDAH
Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.
static intJUMADA_1
Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.
static intJUMADA_2
Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.
static intMUHARRAM
Constant for Muharram, the 1st month of the Islamic year.
static intRABI_1
Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.
static intRABI_2
Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.
static intRAJAB
Constant for Rajab, the 7th month of the Islamic year.
static intRAMADAN
Constant for Ramadan, the 9th month of the Islamic year.
static intSAFAR
Constant for Safar, the 2nd month of the Islamic year.
static intSHABAN
Constant for Sha'ban, the 8th month of the Islamic year.
static intSHAWWAL
Constant for Shawwal, the 10th month of the Islamic year.
Constructor Summary
IslamicCalendar()
Constructs a default IslamicCalendar using the current time in the default time zone with the default locale.
IslamicCalendar(TimeZone zone)
Constructs an IslamicCalendar based on the current time in the given time zone with the default locale.
IslamicCalendar(Locale aLocale)
Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.
IslamicCalendar(ULocale locale)
Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.
IslamicCalendar(TimeZone zone, Locale aLocale)
Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.
IslamicCalendar(TimeZone zone, ULocale locale)
Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.
IslamicCalendar(Date date)
Constructs an IslamicCalendar with the given date set in the default time zone with the default locale.
IslamicCalendar(int year, int month, int date)
Constructs an IslamicCalendar with the given date set in the default time zone with the default locale.
IslamicCalendar(int year, int month, int date, int hour, int minute, int second)
Constructs an IslamicCalendar with the given date and time set for the default time zone with the default locale.
Method Summary
StringgetType()
Return the current Calendar type.
protected voidhandleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Islamic calendar system.
protected inthandleComputeMonthStart(int eyear, int month, boolean useMonth)
protected inthandleGetExtendedYear()
protected inthandleGetLimit(int field, int limitType)
protected inthandleGetMonthLength(int extendedYear, int month)
Return the length (in days) of the given month.
protected inthandleGetYearLength(int extendedYear)
Return the number of days in the given Islamic year
booleanisCivil()
Returns true if this object is using the fixed-cycle civil calendar, or false if using the religious, astronomical calendar.
voidsetCivil(boolean beCivil)
Determines whether this object uses the fixed-cycle Islamic civil calendar or an approximation of the religious, astronomical calendar.

Field Detail

DHU_AL_HIJJAH

public static final int DHU_AL_HIJJAH
Constant for Dhu al-Hijjah, the 12th month of the Islamic year.

UNKNOWN: ICU 2.8

DHU_AL_QIDAH

public static final int DHU_AL_QIDAH
Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.

UNKNOWN: ICU 2.8

JUMADA_1

public static final int JUMADA_1
Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.

UNKNOWN: ICU 2.8

JUMADA_2

public static final int JUMADA_2
Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.

UNKNOWN: ICU 2.8

MUHARRAM

public static final int MUHARRAM
Constant for Muharram, the 1st month of the Islamic year.

UNKNOWN: ICU 2.8

RABI_1

public static final int RABI_1
Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.

UNKNOWN: ICU 2.8

RABI_2

public static final int RABI_2
Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.

UNKNOWN: ICU 2.8

RAJAB

public static final int RAJAB
Constant for Rajab, the 7th month of the Islamic year.

UNKNOWN: ICU 2.8

RAMADAN

public static final int RAMADAN
Constant for Ramadan, the 9th month of the Islamic year.

UNKNOWN: ICU 2.8

SAFAR

public static final int SAFAR
Constant for Safar, the 2nd month of the Islamic year.

UNKNOWN: ICU 2.8

SHABAN

public static final int SHABAN
Constant for Sha'ban, the 8th month of the Islamic year.

UNKNOWN: ICU 2.8

SHAWWAL

public static final int SHAWWAL
Constant for Shawwal, the 10th month of the Islamic year.

UNKNOWN: ICU 2.8

Constructor Detail

IslamicCalendar

public IslamicCalendar()
Constructs a default IslamicCalendar using the current time in the default time zone with the default locale.

UNKNOWN: ICU 2.8

IslamicCalendar

public IslamicCalendar(TimeZone zone)
Constructs an IslamicCalendar based on the current time in the given time zone with the default locale.

Parameters: zone the given time zone.

UNKNOWN: ICU 2.8

IslamicCalendar

public IslamicCalendar(Locale aLocale)
Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

Parameters: aLocale the given locale.

UNKNOWN: ICU 2.8

IslamicCalendar

public IslamicCalendar(ULocale locale)
Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

Parameters: locale the given ulocale.

UNKNOWN: ICU 3.2 This API might change or be removed in a future release.

IslamicCalendar

public IslamicCalendar(TimeZone zone, Locale aLocale)
Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.

Parameters: zone the given time zone. aLocale the given locale.

UNKNOWN: ICU 2.8

IslamicCalendar

public IslamicCalendar(TimeZone zone, ULocale locale)
Constructs an IslamicCalendar based on the current time in the given time zone with the given locale.

Parameters: zone the given time zone. locale the given ulocale.

UNKNOWN: ICU 3.2 This API might change or be removed in a future release.

IslamicCalendar

public IslamicCalendar(Date date)
Constructs an IslamicCalendar with the given date set in the default time zone with the default locale.

Parameters: date The date to which the new calendar is set.

UNKNOWN: ICU 2.8

IslamicCalendar

public IslamicCalendar(int year, int month, int date)
Constructs an IslamicCalendar with the given date set in the default time zone with the default locale.

Parameters: year the value used to set the {@link #YEAR YEAR} time field in the calendar. month the value used to set the {@link #MONTH MONTH} time field in the calendar. Note that the month value is 0-based. e.g., 0 for Muharram. date the value used to set the {@link #DATE DATE} time field in the calendar.

UNKNOWN: ICU 2.8

IslamicCalendar

public IslamicCalendar(int year, int month, int date, int hour, int minute, int second)
Constructs an IslamicCalendar with the given date and time set for the default time zone with the default locale.

Parameters: year the value used to set the {@link #YEAR YEAR} time field in the calendar. month the value used to set the {@link #MONTH MONTH} time field in the calendar. Note that the month value is 0-based. e.g., 0 for Muharram. date the value used to set the {@link #DATE DATE} time field in the calendar. hour the value used to set the {@link #HOUR_OF_DAY HOUR_OF_DAY} time field in the calendar. minute the value used to set the {@link #MINUTE MINUTE} time field in the calendar. second the value used to set the {@link #SECOND SECOND} time field in the calendar.

UNKNOWN: ICU 2.8

Method Detail

getType

public String getType()

Deprecated: This API is ICU internal only.

Return the current Calendar type.

Returns: type of calendar (gregorian, etc.)

UNKNOWN: ICU 3.0

handleComputeFields

protected void handleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Islamic calendar system. These are: The DAY_OF_WEEK and DOW_LOCAL fields are already set when this method is called. The getGregorianXxx() methods return Gregorian calendar equivalents for the given Julian day.

UNKNOWN: ICU 2.8

handleComputeMonthStart

protected int handleComputeMonthStart(int eyear, int month, boolean useMonth)

UNKNOWN: ICU 2.8

handleGetExtendedYear

protected int handleGetExtendedYear()

UNKNOWN: ICU 2.8

handleGetLimit

protected int handleGetLimit(int field, int limitType)

UNKNOWN: ICU 2.8

handleGetMonthLength

protected int handleGetMonthLength(int extendedYear, int month)
Return the length (in days) of the given month.

Parameters: extendedYear The hijri year month The hijri month, 0-based

UNKNOWN: ICU 2.8

handleGetYearLength

protected int handleGetYearLength(int extendedYear)
Return the number of days in the given Islamic year

UNKNOWN: ICU 2.8

isCivil

public boolean isCivil()
Returns true if this object is using the fixed-cycle civil calendar, or false if using the religious, astronomical calendar.

UNKNOWN: ICU 2.8

setCivil

public void setCivil(boolean beCivil)
Determines whether this object uses the fixed-cycle Islamic civil calendar or an approximation of the religious, astronomical calendar.

Parameters: beCivil true to use the civil calendar, false to use the astronomical calendar.

UNKNOWN: ICU 2.8

Copyright (c) 2007 IBM Corporation and others.