Class IslamicChronology

  • All Implemented Interfaces:
    java.io.Serializable

    public final class IslamicChronology
    extends BasicChronology
    Implements the Islamic, or Hijri, calendar system using arithmetic rules.

    This calendar is a lunar calendar with a shorter year than ISO. Year 1 in the Islamic calendar began on July 16, 622 CE (Julian), thus Islamic years do not begin at the same time as Julian years. This chronology is not proleptic, as it does not allow dates before the first Islamic year.

    There are two basic forms of the Islamic calendar, the tabular and the observed. The observed form cannot easily be used by computers as it relies on human observation of the new moon. The tabular calendar, implemented here, is an arithmetical approximation of the observed form that follows relatively simple rules.

    The tabular form of the calendar defines 12 months of alternately 30 and 29 days. The last month is extended to 30 days in a leap year. Leap years occur according to a 30 year cycle. There are four recognised patterns of leap years in the 30 year cycle:

     Years 2, 5, 7, 10, 13, 15, 18, 21, 24, 26 & 29 - 15-based, used by Microsoft
     Years 2, 5, 7, 10, 13, 16, 18, 21, 24, 26 & 29 - 16-based, most commonly used
     Years 2, 5, 8, 10, 13, 16, 19, 21, 24, 27 & 29 - Indian
     Years 2, 5, 8, 11, 13, 16, 19, 21, 24, 27 & 30 - Habash al-Hasib
     
    You can select which pattern to use via the factory methods, or use the default (16-based).

    This implementation defines a day as midnight to midnight exactly as per the ISO chronology. This correct start of day is at sunset on the previous day, however this cannot readily be modelled and has been ignored.

    IslamicChronology is thread-safe and immutable.

    Since:
    1.2
    See Also:
    Wikipedia, Serialized Form
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serialization lock
        See Also:
        Constant Field Values
      • AH

        public static final int AH
        Constant value for 'Anno Hegirae', equivalent to the value returned for AD/CE.
        See Also:
        Constant Field Values
      • ERA_FIELD

        private static final DateTimeField ERA_FIELD
        A singleton era field.
      • MIN_YEAR

        private static final int MIN_YEAR
        The lowest year that can be fully supported.
        See Also:
        Constant Field Values
      • MAX_YEAR

        private static final int MAX_YEAR
        The highest year that can be fully supported. Although calculateFirstDayOfYearMillis can go higher without overflowing, the getYear method overflows when it adds the approximate millis at the epoch.
        See Also:
        Constant Field Values
      • MONTH_PAIR_LENGTH

        private static final int MONTH_PAIR_LENGTH
        The days in a pair of months.
        See Also:
        Constant Field Values
      • LONG_MONTH_LENGTH

        private static final int LONG_MONTH_LENGTH
        The length of the long month.
        See Also:
        Constant Field Values
      • SHORT_MONTH_LENGTH

        private static final int SHORT_MONTH_LENGTH
        The length of the short month.
        See Also:
        Constant Field Values
      • MILLIS_PER_MONTH_PAIR

        private static final long MILLIS_PER_MONTH_PAIR
        The length of the long month in millis.
        See Also:
        Constant Field Values
      • MILLIS_PER_MONTH

        private static final long MILLIS_PER_MONTH
        The length of the long month in millis.
        See Also:
        Constant Field Values
      • MILLIS_PER_LONG_MONTH

        private static final long MILLIS_PER_LONG_MONTH
        The length of the long month in millis.
        See Also:
        Constant Field Values
      • MILLIS_PER_YEAR

        private static final long MILLIS_PER_YEAR
        The typical millis per year.
        See Also:
        Constant Field Values
      • MILLIS_PER_SHORT_YEAR

        private static final long MILLIS_PER_SHORT_YEAR
        The typical millis per year.
        See Also:
        Constant Field Values
      • MILLIS_PER_LONG_YEAR

        private static final long MILLIS_PER_LONG_YEAR
        The typical millis per year.
        See Also:
        Constant Field Values
      • MILLIS_YEAR_1

        private static final long MILLIS_YEAR_1
        The millis of 0001-01-01.
        See Also:
        Constant Field Values
      • CYCLE

        private static final int CYCLE
        The length of the cycle of leap years.
        See Also:
        Constant Field Values
      • MILLIS_PER_CYCLE

        private static final long MILLIS_PER_CYCLE
        The millis of a 30 year cycle.
        See Also:
        Constant Field Values
      • cCache

        private static final java.util.concurrent.ConcurrentHashMap<DateTimeZone,​IslamicChronology[]> cCache
        Cache of zone to chronology arrays
      • INSTANCE_UTC

        private static final IslamicChronology INSTANCE_UTC
        Singleton instance of a UTC IslamicChronology
    • Method Detail

      • getInstanceUTC

        public static IslamicChronology getInstanceUTC()
        Gets an instance of the IslamicChronology. The time zone of the returned instance is UTC.
        Returns:
        a singleton UTC instance of the chronology
      • getInstance

        public static IslamicChronology getInstance()
        Gets an instance of the IslamicChronology in the default time zone.
        Returns:
        a chronology in the default time zone
      • getInstance

        public static IslamicChronology getInstance​(DateTimeZone zone)
        Gets an instance of the IslamicChronology in the given time zone.
        Parameters:
        zone - the time zone to get the chronology in, null is default
        Returns:
        a chronology in the specified time zone
      • getInstance

        public static IslamicChronology getInstance​(DateTimeZone zone,
                                                    IslamicChronology.LeapYearPatternType leapYears)
        Gets an instance of the IslamicChronology in the given time zone.
        Parameters:
        zone - the time zone to get the chronology in, null is default
        leapYears - the type defining the leap year pattern
        Returns:
        a chronology in the specified time zone
      • readResolve

        private java.lang.Object readResolve()
        Serialization singleton.
      • withUTC

        public Chronology withUTC()
        Gets the Chronology in the UTC time zone.
        Specified by:
        withUTC in class BaseChronology
        Returns:
        the chronology in UTC
      • equals

        public boolean equals​(java.lang.Object obj)
        Checks if this chronology instance equals another.
        Overrides:
        equals in class BasicChronology
        Parameters:
        obj - the object to compare to
        Returns:
        true if equal
        Since:
        2.3
      • hashCode

        public int hashCode()
        A suitable hash code for the chronology.
        Overrides:
        hashCode in class BasicChronology
        Returns:
        the hash code
        Since:
        1.6
      • getYear

        int getYear​(long instant)
        Overrides:
        getYear in class BasicChronology
        Parameters:
        instant - millis from 1970-01-01T00:00:00Z
      • setYear

        long setYear​(long instant,
                     int year)
        Description copied from class: BasicChronology
        Sets the year from an instant and year.
        Specified by:
        setYear in class BasicChronology
        Parameters:
        instant - millis from 1970-01-01T00:00:00Z
        year - the year to set
        Returns:
        the updated millis
      • getYearDifference

        long getYearDifference​(long minuendInstant,
                               long subtrahendInstant)
        Description copied from class: BasicChronology
        Gets the difference between the two instants in years.
        Specified by:
        getYearDifference in class BasicChronology
        Parameters:
        minuendInstant - the first instant
        subtrahendInstant - the second instant
        Returns:
        the difference
      • getTotalMillisByYearMonth

        long getTotalMillisByYearMonth​(int year,
                                       int month)
        Description copied from class: BasicChronology
        Gets the total number of millis elapsed in this year at the start of the specified month, such as zero for month 1.
        Specified by:
        getTotalMillisByYearMonth in class BasicChronology
        Parameters:
        year - the year
        month - the month
        Returns:
        the elapsed millis at the start of the month
      • getDayOfMonth

        int getDayOfMonth​(long millis)
        Overrides:
        getDayOfMonth in class BasicChronology
        Parameters:
        millis - from 1970-01-01T00:00:00Z
      • isLeapYear

        boolean isLeapYear​(int year)
        Description copied from class: BasicChronology
        Is the specified year a leap year?
        Specified by:
        isLeapYear in class BasicChronology
        Parameters:
        year - the year to test
        Returns:
        true if leap
      • getDaysInYear

        int getDaysInYear​(int year)
        Description copied from class: BasicChronology
        Get the number of days in the year.
        Overrides:
        getDaysInYear in class BasicChronology
        Parameters:
        year - the year to use
        Returns:
        366 if a leap year, otherwise 365
      • getDaysInYearMonth

        int getDaysInYearMonth​(int year,
                               int month)
        Description copied from class: BasicChronology
        Gets the number of days in the specified month and year.
        Specified by:
        getDaysInYearMonth in class BasicChronology
        Parameters:
        year - the year
        month - the month
        Returns:
        the number of days
      • getDaysInMonthMax

        int getDaysInMonthMax​(int month)
        Description copied from class: BasicChronology
        Gets the maximum days in the specified month.
        Specified by:
        getDaysInMonthMax in class BasicChronology
        Parameters:
        month - the month
        Returns:
        the max days
      • getMonthOfYear

        int getMonthOfYear​(long millis,
                           int year)
        Specified by:
        getMonthOfYear in class BasicChronology
        Parameters:
        millis - from 1970-01-01T00:00:00Z
        year - precalculated year of millis
      • calculateFirstDayOfYearMillis

        long calculateFirstDayOfYearMillis​(int year)
        Description copied from class: BasicChronology
        Gets the millisecond value of the first day of the year.
        Specified by:
        calculateFirstDayOfYearMillis in class BasicChronology
        Returns:
        the milliseconds for the first of the year
      • getApproxMillisAtEpochDividedByTwo

        long getApproxMillisAtEpochDividedByTwo()
        Description copied from class: BasicChronology
        Returns a constant representing the approximate number of milliseconds elapsed from year 0 of this chronology, divided by two. This constant must be defined as:
            (yearAtEpoch * averageMillisPerYear + millisOfYearAtEpoch) / 2
         
        where epoch is 1970-01-01 (Gregorian).
        Specified by:
        getApproxMillisAtEpochDividedByTwo in class BasicChronology
      • assemble

        protected void assemble​(AssembledChronology.Fields fields)
        Description copied from class: AssembledChronology
        Invoked by the constructor and after deserialization to allow subclasses to define all of its supported fields. All unset fields default to unsupported instances.
        Overrides:
        assemble in class BasicChronology
        Parameters:
        fields - container of fields