Class IslamicCalendar
- java.lang.Object
-
- com.ibm.icu.util.Calendar
-
- com.ibm.icu.util.IslamicCalendar
-
- All Implemented Interfaces:
Serializable
,Cloneable
,Comparable<Calendar>
public class IslamicCalendar extends Calendar
IslamicCalendar
is a subclass ofCalendar
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 three 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 and Saudi Arabia's Umm al-Qura calendar, however, are 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 astronomical calculations. At present, the approximations used in this class are fairly simplistic; they will be improved in later versions of the code.
Like the Islamic religious calendar, Umm al-Qura is also based on the sighting method of the crescent moon but is standardized by Saudi Arabia.
The
setCalculationType
method determines which approach is used to determine the start of a month. By default, the fixed-cycle civil calendar is used. However, ifsetCalculationType(ISLAMIC)
is called, an approximation of the true lunar calendar will be used. Similarly, ifsetCalculationType(ISLAMIC_UMALQURA)
is called, an approximation of the Umm al-Qura lunar calendar will be used.This class should not be subclassed.
IslamicCalendar usually should be instantiated using
Calendar.getInstance(ULocale)
passing in aULocale
with the tag"@calendar=islamic"
or"@calendar=islamic-civil"
or"@calendar=islamic-umalqura"
.- Author:
- Laura Werner, Alan Liu
- See Also:
GregorianCalendar
,Calendar
, Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
IslamicCalendar.CalculationType
enumeration of available calendar calculation types-
Nested classes/interfaces inherited from class com.ibm.icu.util.Calendar
Calendar.FormatConfiguration, Calendar.WeekData
-
-
Field Summary
Fields Modifier and Type Field Description static int
DHU_AL_HIJJAH
Constant for Dhu al-Hijjah, the 12th month of the Islamic year.static int
DHU_AL_QIDAH
Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.static int
JUMADA_1
Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.static int
JUMADA_2
Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.static int
MUHARRAM
Constant for Muharram, the 1st month of the Islamic year.static int
RABI_1
Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.static int
RABI_2
Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.static int
RAJAB
Constant for Rajab, the 7th month of the Islamic year.static int
RAMADAN
Constant for Ramadan, the 9th month of the Islamic year.static int
SAFAR
Constant for Safar, the 2nd month of the Islamic year.static int
SHABAN
Constant for Sha'ban, the 8th month of the Islamic year.static int
SHAWWAL
Constant for Shawwal, the 10th month of the Islamic year.-
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, IS_LEAP_MONTH, 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, WALLTIME_FIRST, WALLTIME_LAST, WALLTIME_NEXT_VALID, WEDNESDAY, WEEK_OF_MONTH, WEEK_OF_YEAR, WEEKDAY, WEEKEND, WEEKEND_CEASE, WEEKEND_ONSET, YEAR, YEAR_WOY, ZONE_OFFSET
-
-
Constructor Summary
Constructors Constructor Description IslamicCalendar()
Constructs a defaultIslamicCalendar
using the current time in the default time zone with the defaultFORMAT
locale.IslamicCalendar(int year, int month, int date)
Constructs anIslamicCalendar
with the given date set in the default time zone with the defaultFORMAT
locale.IslamicCalendar(int year, int month, int date, int hour, int minute, int second)
Constructs anIslamicCalendar
with the given date and time set for the default time zone with the defaultFORMAT
locale.IslamicCalendar(TimeZone zone)
Constructs anIslamicCalendar
based on the current time in the given time zone with the defaultFORMAT
locale.IslamicCalendar(TimeZone zone, ULocale locale)
Constructs anIslamicCalendar
based on the current time in the given time zone with the given locale.IslamicCalendar(TimeZone zone, Locale aLocale)
Constructs anIslamicCalendar
based on the current time in the given time zone with the given locale.IslamicCalendar(ULocale locale)
Constructs anIslamicCalendar
based on the current time in the default time zone with the given locale.IslamicCalendar(Date date)
Constructs anIslamicCalendar
with the given date set in the default time zone with the defaultFORMAT
locale.IslamicCalendar(Locale aLocale)
Constructs anIslamicCalendar
based on the current time in the default time zone with the given locale.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description IslamicCalendar.CalculationType
getCalculationType()
gets the calculation type for this calendar.String
getType()
Returns the calendar type name string for this Calendar object.protected void
handleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Islamic calendar system.protected int
handleComputeMonthStart(int eyear, int month, boolean useMonth)
Returns the Julian day number of day before the first day of the given month in the given extended year.protected int
handleGetExtendedYear()
Returns the extended year defined by the current fields.protected int
handleGetLimit(int field, int limitType)
Subclass API for defining limits of different types.protected int
handleGetMonthLength(int extendedYear, int month)
Return the length (in days) of the given month.protected int
handleGetYearLength(int extendedYear)
Return the number of days in the given Islamic yearboolean
isCivil()
Returnstrue
if this object is using the fixed-cycle civil calendar, orfalse
if using the religious, astronomical calendar.void
setCalculationType(IslamicCalendar.CalculationType type)
sets the calculation type for this calendar.void
setCivil(boolean beCivil)
Determines whether this object uses the fixed-cycle Islamic civil calendar or an approximation of the religious, astronomical calendar.-
Methods inherited from class com.ibm.icu.util.Calendar
add, after, before, clear, clear, clone, compareTo, complete, computeFields, computeGregorianFields, computeGregorianMonthStart, computeJulianDay, computeMillisInDay, computeMillisInDayLong, computeTime, computeZoneOffset, computeZoneOffset, equals, fieldDifference, fieldName, floorDivide, floorDivide, floorDivide, floorDivide, get, getActualMaximum, getActualMinimum, getAvailableLocales, getAvailableULocales, getDateTimeFormat, getDateTimeFormat, getDateTimePattern, getDayOfWeekType, getDefaultDayInMonth, getDefaultMonthInYear, getDisplayName, getDisplayName, getFieldCount, getFieldResolutionTable, getFirstDayOfWeek, getGreatestMinimum, getGregorianDayOfMonth, getGregorianDayOfYear, getGregorianMonth, getGregorianYear, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getKeywordValuesForLocale, getLeastMaximum, getLimit, getLocale, getMaximum, getMinimalDaysInFirstWeek, getMinimum, getRelatedYear, getRepeatedWallTimeOption, getSkippedWallTimeOption, getStamp, getTime, getTimeInMillis, getTimeZone, getWeekData, getWeekDataForRegion, getWeekendTransition, gregorianMonthLength, gregorianPreviousMonthLength, handleComputeJulianDay, handleCreateFields, handleGetDateFormat, handleGetDateFormat, handleGetDateFormat, handleGetDateFormat, hashCode, haveDefaultCentury, 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, setRelatedYear, setRepeatedWallTimeOption, setSkippedWallTimeOption, setTime, setTimeInMillis, setTimeZone, setWeekData, toString, validateField, validateField, validateFields, weekNumber, weekNumber
-
-
-
-
Field Detail
-
MUHARRAM
public static final int MUHARRAM
Constant for Muharram, the 1st month of the Islamic year.- See Also:
- Constant Field Values
-
SAFAR
public static final int SAFAR
Constant for Safar, the 2nd month of the Islamic year.- See Also:
- Constant Field Values
-
RABI_1
public static final int RABI_1
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
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
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
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
Constant for Rajab, the 7th month of the Islamic year.- See Also:
- Constant Field Values
-
SHABAN
public static final int SHABAN
Constant for Sha'ban, the 8th month of the Islamic year.- See Also:
- Constant Field Values
-
RAMADAN
public static final int RAMADAN
Constant for Ramadan, the 9th month of the Islamic year.- See Also:
- Constant Field Values
-
SHAWWAL
public static final int SHAWWAL
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
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
Constant for Dhu al-Hijjah, the 12th month of the Islamic year.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
IslamicCalendar
public IslamicCalendar()
Constructs a defaultIslamicCalendar
using the current time in the default time zone with the defaultFORMAT
locale.- See Also:
ULocale.Category.FORMAT
-
IslamicCalendar
public IslamicCalendar(TimeZone zone)
Constructs anIslamicCalendar
based on the current time in the given time zone with the defaultFORMAT
locale.- Parameters:
zone
- the given time zone.- See Also:
ULocale.Category.FORMAT
-
IslamicCalendar
public IslamicCalendar(Locale aLocale)
Constructs anIslamicCalendar
based on the current time in the default time zone with the given locale.- Parameters:
aLocale
- the given locale.
-
IslamicCalendar
public IslamicCalendar(ULocale locale)
Constructs anIslamicCalendar
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)
Constructs anIslamicCalendar
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)
Constructs anIslamicCalendar
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)
Constructs anIslamicCalendar
with the given date set in the default time zone with the defaultFORMAT
locale.- Parameters:
date
- The date to which the new calendar is set.- See Also:
ULocale.Category.FORMAT
-
IslamicCalendar
public IslamicCalendar(int year, int month, int date)
Constructs anIslamicCalendar
with the given date set in the default time zone with the defaultFORMAT
locale.- Parameters:
year
- the value used to set theYEAR
time field in the calendar.month
- the value used to set theMONTH
time field in the calendar. Note that the month value is 0-based. e.g., 0 for Muharram.date
- the value used to set theDATE
time field in the calendar.- See Also:
ULocale.Category.FORMAT
-
IslamicCalendar
public IslamicCalendar(int year, int month, int date, int hour, int minute, int second)
Constructs anIslamicCalendar
with the given date and time set for the default time zone with the defaultFORMAT
locale.- Parameters:
year
- the value used to set theYEAR
time field in the calendar.month
- the value used to set theMONTH
time field in the calendar. Note that the month value is 0-based. e.g., 0 for Muharram.date
- the value used to set theDATE
time field in the calendar.hour
- the value used to set theHOUR_OF_DAY
time field in the calendar.minute
- the value used to set theMINUTE
time field in the calendar.second
- the value used to set theSECOND
time field in the calendar.- See Also:
ULocale.Category.FORMAT
-
-
Method Detail
-
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.
-
isCivil
public boolean isCivil()
Returnstrue
if this object is using the fixed-cycle civil calendar, orfalse
if using the religious, astronomical calendar.
-
handleGetLimit
protected int handleGetLimit(int field, int limitType)
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 classCalendar
- Parameters:
field
- one of the above field numberslimitType
- one ofMINIMUM
,GREATEST_MINIMUM
,LEAST_MAXIMUM
, orMAXIMUM
-
handleGetMonthLength
protected int handleGetMonthLength(int extendedYear, int month)
Return the length (in days) of the given month.- Overrides:
handleGetMonthLength
in classCalendar
- Parameters:
extendedYear
- The hijri yearmonth
- The hijri month, 0-based
-
handleGetYearLength
protected int handleGetYearLength(int extendedYear)
Return the number of days in the given Islamic year- Overrides:
handleGetYearLength
in classCalendar
-
handleComputeMonthStart
protected int handleComputeMonthStart(int eyear, int month, boolean useMonth)
Description copied from class:Calendar
Returns 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 classCalendar
- Parameters:
eyear
- the extended yearmonth
- the zero-based month, or 0 if useMonth is falseuseMonth
- 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()
Description copied from class:Calendar
Returns 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 classCalendar
- Returns:
- the extended year
-
handleComputeFields
protected void handleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Islamic calendar system. These are:- ERA
- YEAR
- MONTH
- DAY_OF_MONTH
- DAY_OF_YEAR
- EXTENDED_YEAR
- Overrides:
handleComputeFields
in classCalendar
-
setCalculationType
public void setCalculationType(IslamicCalendar.CalculationType type)
sets the calculation type for this calendar.
-
getCalculationType
public IslamicCalendar.CalculationType getCalculationType()
gets the calculation type for this calendar.
-
getType
public String getType()
Returns the calendar type name string for this Calendar object. The returned string is the legacy ICU calendar attribute value, for example, "gregorian" or "japanese".See type="old type name" for the calendar attribute of locale IDs at http://www.unicode.org/reports/tr35/#Key_Type_Definitions
-
-