com.ibm.icu.util
Class IslamicCalendar

java.lang.Object
  extended by com.ibm.icu.util.Calendar
      extended by com.ibm.icu.util.IslamicCalendar
All Implemented Interfaces:
Serializable, Cloneable

Deprecated. This is a draft API and might change in a future release of ICU.

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 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.

Note This API has not been promoted to @stable and instead has been left as @draft ICU 2.8. It may yet change or be removed in a future release.

Author:
Laura Werner, Alan Liu
See Also:
GregorianCalendar, Serialized Form

Field Summary
static int DHU_AL_HIJJAH
          Deprecated. This is a draft API and might change in a future release of ICU.
static int DHU_AL_QIDAH
          Deprecated. This is a draft API and might change in a future release of ICU.
static int JUMADA_1
          Deprecated. This is a draft API and might change in a future release of ICU.
static int JUMADA_2
          Deprecated. This is a draft API and might change in a future release of ICU.
static int MUHARRAM
          Deprecated. This is a draft API and might change in a future release of ICU.
static int RABI_1
          Deprecated. This is a draft API and might change in a future release of ICU.
static int RABI_2
          Deprecated. This is a draft API and might change in a future release of ICU.
static int RAJAB
          Deprecated. This is a draft API and might change in a future release of ICU.
static int RAMADAN
          Deprecated. This is a draft API and might change in a future release of ICU.
static int SAFAR
          Deprecated. This is a draft API and might change in a future release of ICU.
static int SHABAN
          Deprecated. This is a draft API and might change in a future release of ICU.
static int SHAWWAL
          Deprecated. This is a draft API and might change in a future release of ICU.
 
Fields inherited from class com.ibm.icu.util.Calendar
AM, AM_PM, APRIL, AUGUST, BASE_FIELD_COUNT, DATE, DAY_OF_MONTH, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, DAY_OF_YEAR, DECEMBER, DOW_LOCAL, DST_OFFSET, EPOCH_JULIAN_DAY, ERA, EXTENDED_YEAR, FEBRUARY, FRIDAY, GREATEST_MINIMUM, HOUR, HOUR_OF_DAY, INTERNALLY_SET, JAN_1_1_JULIAN_DAY, JANUARY, JULIAN_DAY, JULY, JUNE, LEAST_MAXIMUM, MARCH, MAX_DATE, MAX_FIELD_COUNT, MAX_JULIAN, MAX_MILLIS, MAXIMUM, MAY, MILLISECOND, MILLISECONDS_IN_DAY, MIN_DATE, MIN_JULIAN, MIN_MILLIS, MINIMUM, MINIMUM_USER_STAMP, MINUTE, MONDAY, MONTH, NOVEMBER, OCTOBER, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, PM, RESOLVE_REMAP, SATURDAY, SECOND, SEPTEMBER, SUNDAY, THURSDAY, TUESDAY, UNDECIMBER, UNSET, WEDNESDAY, WEEK_OF_MONTH, WEEK_OF_YEAR, WEEKDAY, WEEKEND, WEEKEND_CEASE, WEEKEND_ONSET, YEAR, YEAR_WOY, ZONE_OFFSET
 
Constructor Summary
IslamicCalendar()
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(Date date)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(int year, int month, int date)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(int year, int month, int date, int hour, int minute, int second)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(Locale aLocale)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(TimeZone zone)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(TimeZone zone, Locale aLocale)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(TimeZone zone, ULocale locale)
          Deprecated. This is a draft API and might change in a future release of ICU.
IslamicCalendar(ULocale locale)
          Deprecated. This is a draft API and might change in a future release of ICU.
 
Method Summary
 String getType()
          Deprecated. Return the current Calendar type.
protected  void handleComputeFields(int julianDay)
          Deprecated. This is a draft API and might change in a future release of ICU.
protected  int handleComputeMonthStart(int eyear, int month, boolean useMonth)
          Deprecated. This is a draft API and might change in a future release of ICU.
protected  int handleGetExtendedYear()
          Deprecated. This is a draft API and might change in a future release of ICU.
protected  int handleGetLimit(int field, int limitType)
          Deprecated. This is a draft API and might change in a future release of ICU.
protected  int handleGetMonthLength(int extendedYear, int month)
          Deprecated. This is a draft API and might change in a future release of ICU.
protected  int handleGetYearLength(int extendedYear)
          Deprecated. This is a draft API and might change in a future release of ICU.
 boolean isCivil()
          Deprecated. This is a draft API and might change in a future release of ICU.
 void setCivil(boolean beCivil)
          Deprecated. This is a draft API and might change in a future release of ICU.
 
Methods inherited from class com.ibm.icu.util.Calendar
add, after, before, clear, clear, clone, complete, computeFields, computeGregorianFields, computeGregorianMonthStart, computeJulianDay, computeMillisInDay, computeTime, computeZoneOffset, equals, fieldDifference, fieldName, floorDivide, floorDivide, floorDivide, floorDivide, get, getActualMaximum, getActualMinimum, getAvailableLocales, getAvailableULocales, getDateTimeFormat, getDateTimeFormat, getDayOfWeekType, getDisplayName, getDisplayName, getFieldCount, getFieldResolutionTable, getFirstDayOfWeek, getGreatestMinimum, getGregorianDayOfMonth, getGregorianDayOfYear, getGregorianMonth, getGregorianYear, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getLeastMaximum, getLimit, getLocale, getMaximum, getMinimalDaysInFirstWeek, getMinimum, getStamp, getTime, getTimeInMillis, getTimeZone, getWeekendTransition, gregorianMonthLength, gregorianPreviousMonthLength, handleComputeJulianDay, handleCreateFields, handleGetDateFormat, handleGetDateFormat, hashCode, internalGet, internalGet, internalGetTimeInMillis, internalSet, isEquivalentTo, isGregorianLeapYear, isLenient, isSet, isWeekend, isWeekend, julianDayToDayOfWeek, julianDayToMillis, millisToJulianDay, newerField, newestStamp, pinField, prepareGetActual, resolveFields, roll, roll, set, set, set, set, setFirstDayOfWeek, setLenient, setMinimalDaysInFirstWeek, setTime, setTimeInMillis, setTimeZone, toString, validateField, validateField, validateFields, weekNumber, weekNumber
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MUHARRAM

public static final int MUHARRAM
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Muharram, the 1st month of the Islamic year.

See Also:
Constant Field Values

SAFAR

public static final int SAFAR
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Safar, the 2nd month of the Islamic year.

See Also:
Constant Field Values

RABI_1

public static final int RABI_1
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.

See Also:
Constant Field Values

RABI_2

public static final int RABI_2
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.

See Also:
Constant Field Values

JUMADA_1

public static final int JUMADA_1
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.

See Also:
Constant Field Values

JUMADA_2

public static final int JUMADA_2
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.

See Also:
Constant Field Values

RAJAB

public static final int RAJAB
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Rajab, the 7th month of the Islamic year.

See Also:
Constant Field Values

SHABAN

public static final int SHABAN
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Sha'ban, the 8th month of the Islamic year.

See Also:
Constant Field Values

RAMADAN

public static final int RAMADAN
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Ramadan, the 9th month of the Islamic year.

See Also:
Constant Field Values

SHAWWAL

public static final int SHAWWAL
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Shawwal, the 10th month of the Islamic year.

See Also:
Constant Field Values

DHU_AL_QIDAH

public static final int DHU_AL_QIDAH
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.

See Also:
Constant Field Values

DHU_AL_HIJJAH

public static final int DHU_AL_HIJJAH
Deprecated. This is a draft API and might change in a future release of ICU.
Constant for Dhu al-Hijjah, the 12th month of the Islamic year.

See Also:
Constant Field Values
Constructor Detail

IslamicCalendar

public IslamicCalendar()
Deprecated. This is a draft API and might change in a future release of ICU.

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


IslamicCalendar

public IslamicCalendar(TimeZone zone)
Deprecated. This is a draft API and might change in a future release of ICU.

Constructs an IslamicCalendar based on the current time in the given time zone with the default locale.

Parameters:
zone - the given time zone.

IslamicCalendar

public IslamicCalendar(Locale aLocale)
Deprecated. This is a draft API and might change in a future release of ICU.

Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

Parameters:
aLocale - the given locale.

IslamicCalendar

public IslamicCalendar(ULocale locale)
Deprecated. This is a draft API and might change in a future release of ICU.

Constructs an IslamicCalendar based on the current time in the default time zone with the given locale.

Parameters:
locale - the given ulocale.

IslamicCalendar

public IslamicCalendar(TimeZone zone,
                       Locale aLocale)
Deprecated. This is a draft API and might change in a future release of ICU.

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.

IslamicCalendar

public IslamicCalendar(TimeZone zone,
                       ULocale locale)
Deprecated. This is a draft API and might change in a future release of ICU.

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.

IslamicCalendar

public IslamicCalendar(Date date)
Deprecated. This is a draft API and might change in a future release of ICU.

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.

IslamicCalendar

public IslamicCalendar(int year,
                       int month,
                       int date)
Deprecated. This is a draft API and might change in a future release of ICU.

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 YEAR time field in the calendar.
month - the value used to set the 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 DATE time field in the calendar.

IslamicCalendar

public IslamicCalendar(int year,
                       int month,
                       int date,
                       int hour,
                       int minute,
                       int second)
Deprecated. This is a draft API and might change in a future release of ICU.

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 YEAR time field in the calendar.
month - the value used to set the 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 DATE time field in the calendar.
hour - the value used to set the HOUR_OF_DAY time field in the calendar.
minute - the value used to set the MINUTE time field in the calendar.
second - the value used to set the SECOND time field in the calendar.
Method Detail

setCivil

public void setCivil(boolean beCivil)
Deprecated. This is a draft API and might change in a future release of ICU.

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.

isCivil

public boolean isCivil()
Deprecated. This is a draft API and might change in a future release of ICU.

Returns true if this object is using the fixed-cycle civil calendar, or false if using the religious, astronomical calendar.


handleGetLimit

protected int handleGetLimit(int field,
                             int limitType)
Deprecated. This is a draft API and might change in a future release of ICU.

Description copied from class: Calendar
Subclass API for defining limits of different types. Subclasses must implement this method to return limits for the following fields:
ERA
 YEAR
 MONTH
 WEEK_OF_YEAR
 WEEK_OF_MONTH
 DAY_OF_MONTH
 DAY_OF_YEAR
 DAY_OF_WEEK_IN_MONTH
 YEAR_WOY
 EXTENDED_YEAR

Specified by:
handleGetLimit in class Calendar
Parameters:
field - one of the above field numbers
limitType - one of MINIMUM, GREATEST_MINIMUM, LEAST_MAXIMUM, or MAXIMUM

handleGetMonthLength

protected int handleGetMonthLength(int extendedYear,
                                   int month)
Deprecated. This is a draft API and might change in a future release of ICU.

Return the length (in days) of the given month.

Overrides:
handleGetMonthLength in class Calendar
Parameters:
extendedYear - The hijri year
month - The hijri month, 0-based

handleGetYearLength

protected int handleGetYearLength(int extendedYear)
Deprecated. This is a draft API and might change in a future release of ICU.

Return the number of days in the given Islamic year

Overrides:
handleGetYearLength in class Calendar

handleComputeMonthStart

protected int handleComputeMonthStart(int eyear,
                                      int month,
                                      boolean useMonth)
Deprecated. This is a draft API and might change in a future release of ICU.

Description copied from class: Calendar
Return the Julian day number of day before the first day of the given month in the given extended year. Subclasses should override this method to implement their calendar system.

Specified by:
handleComputeMonthStart in class Calendar
Parameters:
eyear - the extended year
month - the zero-based month, or 0 if useMonth is false
useMonth - if false, compute the day before the first day of the given year, otherwise, compute the day before the first day of the given month
Returns:
the Julian day number of the day before the first day of the given month and year

handleGetExtendedYear

protected int handleGetExtendedYear()
Deprecated. This is a draft API and might change in a future release of ICU.

Description copied from class: Calendar
Return the extended year defined by the current fields. This will use the EXTENDED_YEAR field or the YEAR and supra-year fields (such as ERA) specific to the calendar system, depending on which set of fields is newer.

Specified by:
handleGetExtendedYear in class Calendar
Returns:
the extended year

handleComputeFields

protected void handleComputeFields(int julianDay)
Deprecated. This is a draft API and might change in a future release of ICU.

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.

Overrides:
handleComputeFields in class Calendar

getType

public String getType()
Deprecated. 
Return the current Calendar type.

Overrides:
getType in class Calendar
Returns:
type of calendar (gregorian, etc.)


Copyright (c) 2004 IBM Corporation and others.