http://www.joda.org/joda-time/: Date and time library to replace JDK date handling (Joda.org) 
/*
 *  Copyright 2001-2005 Stephen Colebourne
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.joda.time;



Chronology provides access to the individual date time fields for a
chronological calendar system.


Various chronologies are supported by subclasses including ISO
and GregorianJulian. To construct a Chronology you should use the
factory methods on the chronology subclass in the chrono package.


For example, to obtain the current time in the coptic calendar system:

DateTime dt = new DateTime(CopticChronology.getInstance());




The provided chronology implementations are:

    

  • ISO - The de facto world calendar system, based on the ISO-8601 standard

  • GJ - Historically accurate calendar with Julian followed by Gregorian

  • Gregorian - The Gregorian calendar system used for all time (proleptic)

  • Julian - The Julian calendar system used for all time (proleptic)

  • Buddhist - The Buddhist calendar system which is an offset in years from GJ

  • Coptic - The Coptic calendar system which defines 30 day months

  • Ethiopic - The Ethiopic calendar system which defines 30 day months

  • Islamic - The Islamic, or Hijri, lunar calendar system


Hopefully future releases will contain more chronologies.


This class defines a number of fields with names from the ISO8601 standard.
It does not 'strongly' define these fields however, thus implementations
are free to interpret the field names as they wish.
For example, a week could be defined as 10 days and a month as 40 days in a
special WeirdChronology implementation. Clearly the GJ and ISO
implementations provided use the field names as you would expect.

Author:Stephen Colebourne, Brian S O'Neill
See Also:
Since:1.0
/**
 * Chronology provides access to the individual date time fields for a
 * chronological calendar system.
 * <p>
 * Various chronologies are supported by subclasses including ISO
 * and GregorianJulian. To construct a Chronology you should use the
 * factory methods on the chronology subclass in the chrono package.
 * <p>
 * For example, to obtain the current time in the coptic calendar system:
 * <pre>
 * DateTime dt = new DateTime(CopticChronology.getInstance());
 * </pre>
 * <p>
 * The provided chronology implementations are:
 * <ul>
 * <li>ISO - The <i>de facto<i> world calendar system, based on the ISO-8601 standard
 * <li>GJ - Historically accurate calendar with Julian followed by Gregorian
 * <li>Gregorian - The Gregorian calendar system used for all time (proleptic)
 * <li>Julian - The Julian calendar system used for all time (proleptic)
 * <li>Buddhist - The Buddhist calendar system which is an offset in years from GJ
 * <li>Coptic - The Coptic calendar system which defines 30 day months
 * <li>Ethiopic - The Ethiopic calendar system which defines 30 day months
 * <li>Islamic - The Islamic, or Hijri, lunar calendar system
 * </ul>
 * Hopefully future releases will contain more chronologies.
 * <p>
 * This class defines a number of fields with names from the ISO8601 standard.
 * It does not 'strongly' define these fields however, thus implementations
 * are free to interpret the field names as they wish.
 * For example, a week could be defined as 10 days and a month as 40 days in a
 * special WeirdChronology implementation. Clearly the GJ and ISO
 * implementations provided use the field names as you would expect.
 *
 * @see org.joda.time.chrono.ISOChronology
 * @see org.joda.time.chrono.GJChronology
 * @see org.joda.time.chrono.GregorianChronology
 * @see org.joda.time.chrono.JulianChronology
 * @see org.joda.time.chrono.CopticChronology
 * @see org.joda.time.chrono.BuddhistChronology
 * @see org.joda.time.chrono.EthiopicChronology
 * @see org.joda.time.chrono.IslamicChronology
 *
 * @author Stephen Colebourne
 * @author Brian S O'Neill
 * @since 1.0
 */
public abstract class Chronology {

    
Returns the DateTimeZone that this Chronology operates in, or null if
unspecified.

Returns:the DateTimeZone, null if unspecified
/**
     * Returns the DateTimeZone that this Chronology operates in, or null if
     * unspecified.
     *
     * @return the DateTimeZone, null if unspecified
     */
    public abstract DateTimeZone getZone();

    
Returns an instance of this Chronology that operates in the UTC time
zone. Chronologies that do not operate in a time zone or are already
UTC must return themselves.

Returns:a version of this chronology that ignores time zones
/**
     * Returns an instance of this Chronology that operates in the UTC time
     * zone. Chronologies that do not operate in a time zone or are already
     * UTC must return themselves.
     *
     * @return a version of this chronology that ignores time zones
     */
    public abstract Chronology withUTC();
    
    
Returns an instance of this Chronology that operates in any time zone.

Params:
  • zone – to use, or default if null
See Also:
Returns:a version of this chronology with a specific time zone
/**
     * Returns an instance of this Chronology that operates in any time zone.
     *
     * @return a version of this chronology with a specific time zone
     * @param zone to use, or default if null
     * @see org.joda.time.chrono.ZonedChronology
     */
    public abstract Chronology withZone(DateTimeZone zone);

    
Returns a datetime millisecond instant, formed from the given year,
month, day, and millisecond values. The set of given values must refer
to a valid datetime, or else an IllegalArgumentException is thrown.


The default implementation calls upon separate DateTimeFields to
determine the result. Subclasses are encouraged to provide a more
efficient implementation.

Params:
  • year – year to use
  • monthOfYear – month to use
  • dayOfMonth – day of month to use
  • millisOfDay – millisecond to use
Throws:
Returns:millisecond instant from 1970-01-01T00:00:00Z
/**
     * Returns a datetime millisecond instant, formed from the given year,
     * month, day, and millisecond values. The set of given values must refer
     * to a valid datetime, or else an IllegalArgumentException is thrown.
     * <p>
     * The default implementation calls upon separate DateTimeFields to
     * determine the result. Subclasses are encouraged to provide a more
     * efficient implementation.
     *
     * @param year year to use
     * @param monthOfYear month to use
     * @param dayOfMonth day of month to use
     * @param millisOfDay millisecond to use
     * @return millisecond instant from 1970-01-01T00:00:00Z
     * @throws IllegalArgumentException if the values are invalid
     */
    public abstract long getDateTimeMillis(int year, int monthOfYear, int dayOfMonth, int millisOfDay);

    
Returns a datetime millisecond instant, formed from the given year,
month, day, hour, minute, second, and millisecond values. The set of
given values must refer to a valid datetime, or else an
IllegalArgumentException is thrown.


The default implementation calls upon separate DateTimeFields to
determine the result. Subclasses are encouraged to provide a more
efficient implementation.

Params:
  • year – year to use
  • monthOfYear – month to use
  • dayOfMonth – day of month to use
  • hourOfDay – hour to use
  • minuteOfHour – minute to use
  • secondOfMinute – second to use
  • millisOfSecond – millisecond to use
Throws:
Returns:millisecond instant from 1970-01-01T00:00:00Z
/**
     * Returns a datetime millisecond instant, formed from the given year,
     * month, day, hour, minute, second, and millisecond values. The set of
     * given values must refer to a valid datetime, or else an
     * IllegalArgumentException is thrown.
     * <p>
     * The default implementation calls upon separate DateTimeFields to
     * determine the result. Subclasses are encouraged to provide a more
     * efficient implementation.
     *
     * @param year year to use
     * @param monthOfYear month to use
     * @param dayOfMonth day of month to use
     * @param hourOfDay hour to use
     * @param minuteOfHour minute to use
     * @param secondOfMinute second to use
     * @param millisOfSecond millisecond to use
     * @return millisecond instant from 1970-01-01T00:00:00Z
     * @throws IllegalArgumentException if the values are invalid
     */
    public abstract long getDateTimeMillis(int year, int monthOfYear, int dayOfMonth,
                           int hourOfDay, int minuteOfHour,
                           int secondOfMinute, int millisOfSecond);

    
Returns a datetime millisecond instant, from from the given instant,
hour, minute, second, and millisecond values. The set of given values
must refer to a valid datetime, or else an IllegalArgumentException is
thrown.


The default implementation calls upon separate DateTimeFields to
determine the result. Subclasses are encouraged to provide a more
efficient implementation.

Params:
  • instant – instant to start from
  • hourOfDay – hour to use
  • minuteOfHour – minute to use
  • secondOfMinute – second to use
  • millisOfSecond – millisecond to use
Throws:
Returns:millisecond instant from 1970-01-01T00:00:00Z
/**
     * Returns a datetime millisecond instant, from from the given instant,
     * hour, minute, second, and millisecond values. The set of given values
     * must refer to a valid datetime, or else an IllegalArgumentException is
     * thrown.
     * <p>
     * The default implementation calls upon separate DateTimeFields to
     * determine the result. Subclasses are encouraged to provide a more
     * efficient implementation.
     *
     * @param instant instant to start from
     * @param hourOfDay hour to use
     * @param minuteOfHour minute to use
     * @param secondOfMinute second to use
     * @param millisOfSecond millisecond to use
     * @return millisecond instant from 1970-01-01T00:00:00Z
     * @throws IllegalArgumentException if the values are invalid
     */
    public abstract long getDateTimeMillis(long instant,
                           int hourOfDay, int minuteOfHour,
                           int secondOfMinute, int millisOfSecond);

    //-----------------------------------------------------------------------
    
Validates whether the values are valid for the fields of a partial instant.

Params:
  • partial –  the partial instant to validate
  • values –  the values to validate, not null, match fields in partial
Throws:
/**
     * Validates whether the values are valid for the fields of a partial instant.
     *
     * @param partial  the partial instant to validate
     * @param values  the values to validate, not null, match fields in partial
     * @throws IllegalArgumentException if the instant is invalid
     */
    public abstract void validate(ReadablePartial partial, int[] values);

    
Gets the values of a partial from an instant.

Params:
  • partial –  the partial instant to use
  • instant –  the instant to query
Returns:the values of this partial extracted from the instant
/**
     * Gets the values of a partial from an instant.
     *
     * @param partial  the partial instant to use
     * @param instant  the instant to query
     * @return the values of this partial extracted from the instant
     */
    public abstract int[] get(ReadablePartial partial, long instant);

    
Sets the partial into the instant.

Params:
  • partial –  the partial instant to use
  • instant –  the instant to update
Returns:the updated instant
/**
     * Sets the partial into the instant.
     *
     * @param partial  the partial instant to use
     * @param instant  the instant to update
     * @return the updated instant
     */
    public abstract long set(ReadablePartial partial, long instant);

    //-----------------------------------------------------------------------
    
Gets the values of a period from an interval.

Params:
  • period –  the period instant to use
  • startInstant –  the start instant of an interval to query
  • endInstant –  the start instant of an interval to query
Returns:the values of the period extracted from the interval
/**
     * Gets the values of a period from an interval.
     *
     * @param period  the period instant to use
     * @param startInstant  the start instant of an interval to query
     * @param endInstant  the start instant of an interval to query
     * @return the values of the period extracted from the interval
     */
    public abstract int[] get(ReadablePeriod period, long startInstant, long endInstant);

    
Gets the values of a period from an interval.

Params:
  • period –  the period instant to use
  • duration –  the duration to query
Returns:the values of the period extracted from the duration
/**
     * Gets the values of a period from an interval.
     *
     * @param period  the period instant to use
     * @param duration  the duration to query
     * @return the values of the period extracted from the duration
     */
    public abstract int[] get(ReadablePeriod period, long duration);

    
Adds the period to the instant, specifying the number of times to add.

Params:
  • period –  the period to add, null means add nothing
  • instant –  the instant to add to
  • scalar –  the number of times to add
Returns:the updated instant
/**
     * Adds the period to the instant, specifying the number of times to add.
     *
     * @param period  the period to add, null means add nothing
     * @param instant  the instant to add to
     * @param scalar  the number of times to add
     * @return the updated instant
     */
    public abstract long add(ReadablePeriod period, long instant, int scalar);

    //-----------------------------------------------------------------------
    
Adds the duration to the instant, specifying the number of times to add.

Params:
  • instant –  the instant to add to
  • duration –  the duration to add
  • scalar –  the number of times to add
Returns:the updated instant
/**
     * Adds the duration to the instant, specifying the number of times to add.
     *
     * @param instant  the instant to add to
     * @param duration  the duration to add
     * @param scalar  the number of times to add
     * @return the updated instant
     */
    public abstract long add(long instant, long duration, int scalar);

    // Millis
    //-----------------------------------------------------------------------
    
Get the millis duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the millis duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField millis();

    
Get the millis of second field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the millis of second field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField millisOfSecond();

    
Get the millis of day field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the millis of day field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField millisOfDay();

    // Second
    //-----------------------------------------------------------------------
    
Get the seconds duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the seconds duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField seconds();

    
Get the second of minute field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the second of minute field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField secondOfMinute();

    
Get the second of day field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the second of day field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField secondOfDay();

    // Minute
    //-----------------------------------------------------------------------
    
Get the minutes duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the minutes duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField minutes();

    
Get the minute of hour field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the minute of hour field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField minuteOfHour();

    
Get the minute of day field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the minute of day field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField minuteOfDay();

    // Hour
    //-----------------------------------------------------------------------
    
Get the hours duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the hours duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField hours();

    
Get the hour of day (0-23) field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the hour of day (0-23) field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField hourOfDay();

    
Get the hour of day (offset to 1-24) field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the hour of day (offset to 1-24) field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField clockhourOfDay();

    // Halfday
    //-----------------------------------------------------------------------
    
Get the halfdays duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the halfdays duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField halfdays();

    
Get the hour of am/pm (0-11) field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the hour of am/pm (0-11) field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField hourOfHalfday();

    
Get the hour of am/pm (offset to 1-12) field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the hour of am/pm (offset to 1-12) field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField clockhourOfHalfday();

    
Get the AM(0) PM(1) field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the AM(0) PM(1) field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField halfdayOfDay();

    // Day
    //-----------------------------------------------------------------------
    
Get the days duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the days duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField days();

    
Get the day of week field for this chronology.

DayOfWeek values are defined in DateTimeConstants. They use the ISO definitions, where 1 is Monday and 7 is Sunday. 
Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the day of week field for this chronology.
     *
     * <p>DayOfWeek values are defined in {@link DateTimeConstants}.
     * They use the ISO definitions, where 1 is Monday and 7 is Sunday.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField dayOfWeek();

    
Get the day of month field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the day of month field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField dayOfMonth();

    
Get the day of year field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the day of year field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField dayOfYear();

    // Week
    //-----------------------------------------------------------------------
    
Get the weeks duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the weeks duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField weeks();

    
Get the week of a week based year field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the week of a week based year field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField weekOfWeekyear();

    // Weekyear
    //-----------------------------------------------------------------------
    
Get the weekyears duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the weekyears duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField weekyears();

    
Get the year of a week based year field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the year of a week based year field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField weekyear();

    
Get the year of a week based year in a century field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the year of a week based year in a century field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract  DateTimeField weekyearOfCentury();

    // Month
    //-----------------------------------------------------------------------
    
Get the months duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the months duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField months();

    
Get the month of year field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the month of year field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField monthOfYear();

    // Year
    //-----------------------------------------------------------------------
    
Get the years duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the years duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField years();

    
Get the year field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the year field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField year();

    
Get the year of era field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the year of era field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField yearOfEra();

    
Get the year of century field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the year of century field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField yearOfCentury();

    // Century
    //-----------------------------------------------------------------------
    
Get the centuries duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the centuries duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField centuries();

    
Get the century of era field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the century of era field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField centuryOfEra();

    // Era
    //-----------------------------------------------------------------------
    
Get the eras duration field for this chronology.

Returns:DurationField or UnsupportedDurationField if unsupported
/**
     * Get the eras duration field for this chronology.
     * 
     * @return DurationField or UnsupportedDurationField if unsupported
     */
    public abstract DurationField eras();

    
Get the era field for this chronology.

Returns:DateTimeField or UnsupportedDateTimeField if unsupported
/**
     * Get the era field for this chronology.
     * 
     * @return DateTimeField or UnsupportedDateTimeField if unsupported
     */
    public abstract DateTimeField era();

    //-----------------------------------------------------------------------
    
Gets a debugging toString.

Returns:a debugging string
/**
     * Gets a debugging toString.
     * 
     * @return a debugging string
     */
    public abstract String toString();

}