An abstract implementation of a calendar system, used to organize and identify dates.

The main date and time API is built on the ISO calendar system.
The chronology operates behind the scenes to represent the general concept of a calendar system.

See Chronology for more details.

A date without time-of-day or time-zone in an arbitrary chronology, intended
for advanced globalization use cases.

Most applications should declare method signatures, fields and variables
as LocalDate, not this interface.

A ChronoLocalDate is the abstract representation of a date where the
Chronology chronology, or calendar system, is pluggable.
The date is defined in terms of fields expressed by TemporalField,
where most common implementations are defined in ChronoField.
The chronology defines how the calendar system operates and the meaning of
the standard fields.

When to use this interface
The design of the API encourages the use of LocalDate rather than this
interface, even in the case where the application needs to deal with multiple
calendar systems.

This concept can seem surprising at first, as the natural way to globalize an
application might initially appear to be to abstract the calendar system.
However, as explored below, abstracting the calendar system is usually the wrong
approach, resulting in logic errors and hard to find bugs.
As such, it should be considered an application-wide architectural decision to choose
to use this interface as opposed to LocalDate.

Architectural issues to consider
These are some of the points that must be considered before using this interface
throughout an application.

1) Applications using this interface, as opposed to using just LocalDate,
face a significantly higher probability of bugs. This is because the calendar system
in use is not known at development time. A key cause of bugs is where the developer
applies assumptions from their day-to-day knowledge of the ISO calendar system
to code that is intended to deal with any arbitrary calendar system.
The section below outlines how those assumptions can cause problems
The primary mechanism for reducing this increased risk of bugs is a strong code review process.
This should also be considered a extra cost in maintenance for the lifetime of the code.

2) This interface does not enforce immutability of implementations.
While the implementation notes indicate that all implementations must be immutable
there is nothing in the code or type system to enforce this. Any method declared
to accept a ChronoLocalDate could therefore be passed a poorly or
maliciously written mutable implementation.

3) Applications using this interface  must consider the impact of eras.
LocalDate shields users from the concept of eras, by ensuring that getYear()
returns the proleptic year. That decision ensures that developers can think of
LocalDate instances as consisting of three fields - year, month-of-year and day-of-month.
By contrast, users of this interface must think of dates as consisting of four fields -
era, year-of-era, month-of-year and day-of-month. The extra era field is frequently
forgotten, yet it is of vital importance to dates in an arbitrary calendar system.
For example, in the Japanese calendar system, the era represents the reign of an Emperor.
Whenever one reign ends and another starts, the year-of-era is reset to one.

4) The only agreed international standard for passing a date between two systems
is the ISO-8601 standard which requires the ISO calendar system. Using this interface
throughout the application will inevitably lead to the requirement to pass the date
across a network or component boundary, requiring an application specific protocol or format.

5) Long term persistence, such as a database, will almost always only accept dates in the
ISO-8601 calendar system (or the related Julian-Gregorian). Passing around dates in other
calendar systems increases the complications of interacting with persistence.

6) Most of the time, passing a ChronoLocalDate throughout an application
is unnecessary, as discussed in the last section below.

False assumptions causing bugs in multi-calendar system code
As indicated above, there are many issues to consider when try to use and manipulate a
date in an arbitrary calendar system. These are some of the key issues.

Code that queries the day-of-month and assumes that the value will never be more than
31 is invalid. Some calendar systems have more than 31 days in some months.

Code that adds 12 months to a date and assumes that a year has been added is invalid.
Some calendar systems have a different number of months, such as 13 in the Coptic or Ethiopic.

Code that adds one month to a date and assumes that the month-of-year value will increase
by one or wrap to the next year is invalid. Some calendar systems have a variable number
of months in a year, such as the Hebrew.

Code that adds one month, then adds a second one month and assumes that the day-of-month
will remain close to its original value is invalid. Some calendar systems have a large difference
between the length of the longest month and the length of the shortest month.
For example, the Coptic or Ethiopic have 12 months of 30 days and 1 month of 5 days.

Code that adds seven days and assumes that a week has been added is invalid.
Some calendar systems have weeks of other than seven days, such as the French Revolutionary.

Code that assumes that because the year of date1 is greater than the year of date2
then date1 is after date2 is invalid. This is invalid for all calendar systems
when referring to the year-of-era, and especially untrue of the Japanese calendar system
where the year-of-era restarts with the reign of every new Emperor.

Code that treats month-of-year one and day-of-month one as the start of the year is invalid.
Not all calendar systems start the year when the month value is one.

In general, manipulating a date, and even querying a date, is wide open to bugs when the
calendar system is unknown at development time. This is why it is essential that code using
this interface is subjected to additional code reviews. It is also why an architectural
decision to avoid this interface type is usually the correct one.

Using LocalDate instead
The primary alternative to using this interface throughout your application is as follows.

Declare all method signatures referring to dates in terms of LocalDate.
Either store the chronology (calendar system) in the user profile or lookup
 the chronology from the user locale
Convert the ISO LocalDate to and from the user's preferred calendar system during
 printing and parsing

This approach treats the problem of globalized calendar systems as a localization issue
and confines it to the UI layer. This approach is in keeping with other localization
issues in the java platform.

As discussed above, performing calculations on a date where the rules of the calendar system
are pluggable requires skill and is not recommended.
Fortunately, the need to perform calculations on a date in an arbitrary calendar system
is extremely rare. For example, it is highly unlikely that the business rules of a library
book rental scheme will allow rentals to be for one month, where meaning of the month
is dependent on the user's preferred calendar system.

A key use case for calculations on a date in an arbitrary calendar system is producing
a month-by-month calendar for display and user interaction. Again, this is a UI issue,
and use of this interface solely within a few methods of the UI layer may be justified.

In any other part of the system, where a date must be manipulated in a calendar system
other than ISO, the use case will generally specify the calendar system to use.
For example, an application may need to calculate the next Islamic or Hebrew holiday
which may require manipulating the date.
This kind of use case can be handled as follows:

start from the ISO LocalDate being passed to the method
convert the date to the alternate calendar system, which for this use case is known
 rather than arbitrary
perform the calculation
convert back to LocalDate

Developers writing low-level frameworks or libraries should also avoid this interface.
Instead, one of the two general purpose access interfaces should be used.
Use TemporalAccessor if read-only access is required, or use Temporal
if read-write access is required.

A date-time without a time-zone in an arbitrary chronology, intended
for advanced globalization use cases.

Most applications should declare method signatures, fields and variables
as LocalDateTime, not this interface.

A ChronoLocalDateTime is the abstract representation of a local date-time
where the Chronology chronology, or calendar system, is pluggable.
The date-time is defined in terms of fields expressed by TemporalField,
where most common implementations are defined in ChronoField.
The chronology defines how the calendar system operates and the meaning of
the standard fields.

When to use this interface
The design of the API encourages the use of LocalDateTime rather than this
interface, even in the case where the application needs to deal with multiple
calendar systems. The rationale for this is explored in detail in ChronoLocalDate.

Ensure that the discussion in ChronoLocalDate has been read and understood
before using this interface.

A calendar system, used to organize and identify dates.

The main date and time API is built on the ISO calendar system.
The chronology operates behind the scenes to represent the general concept of a calendar system.
For example, the Japanese, Minguo, Thai Buddhist and others.

Most other calendar systems also operate on the shared concepts of year, month and day,
linked to the cycles of the Earth around the Sun, and the Moon around the Earth.
These shared concepts are defined by ChronoField and are available
for use by any Chronology implementation:


  LocalDate isoDate = ...
  ThaiBuddhistDate thaiDate = ...
  int isoYear = isoDate.get(ChronoField.YEAR);
  int thaiYear = thaiDate.get(ChronoField.YEAR);
As shown, although the date objects are in different calendar systems, represented by different
Chronology instances, both can be queried using the same constant on ChronoField.
For a full discussion of the implications of this, see ChronoLocalDate.
In general, the advice is to use the known ISO-based LocalDate, rather than
ChronoLocalDate.

While a Chronology object typically uses ChronoField and is based on
an era, year-of-era, month-of-year, day-of-month model of a date, this is not required.
A Chronology instance may represent a totally different kind of calendar system,
such as the Mayan.

In practical terms, the Chronology instance also acts as a factory.
The of(String) method allows an instance to be looked up by identifier,
while the ofLocale(Locale) method allows lookup by locale.

The Chronology instance provides a set of methods to create ChronoLocalDate instances.
The date classes are used to manipulate specific dates.

 dateNow()
 dateNow(clock)
 dateNow(zone)
 date(yearProleptic, month, day)
 date(era, yearOfEra, month, day)
 dateYearDay(yearProleptic, dayOfYear)
 dateYearDay(era, yearOfEra, dayOfYear)
 date(TemporalAccessor)


Adding New Calendars
The set of available chronologies can be extended by applications.
Adding a new calendar system requires the writing of an implementation of
Chronology, ChronoLocalDate and Era.
The majority of the logic specific to the calendar system will be in the
ChronoLocalDate implementation.
The Chronology implementation acts as a factory.

To permit the discovery of additional chronologies, the ServiceLoader
is used. A file must be added to the META-INF/services directory with the
name 'java.time.chrono.Chronology' listing the implementation classes.
See the ServiceLoader for more details on service loading.
For lookup by id or calendarType, the system provided calendars are found
first followed by application provided calendars.

Each chronology must define a chronology ID that is unique within the system.
If the chronology represents a calendar system defined by the
CLDR specification then the calendar type is the concatenation of the
CLDR type and, if applicable, the CLDR variant,

A date-based amount of time, such as '3 years, 4 months and 5 days' in an
arbitrary chronology, intended for advanced globalization use cases.

This interface models a date-based amount of time in a calendar system.
While most calendar systems use years, months and days, some do not.
Therefore, this interface operates solely in terms of a set of supported
units that are defined by the Chronology.
The set of supported units is fixed for a given chronology.
The amount of a supported unit may be set to zero.

The period is modeled as a directed amount of time, meaning that individual
parts of the period may be negative.

A date-time with a time-zone in an arbitrary chronology,
intended for advanced globalization use cases.

Most applications should declare method signatures, fields and variables
as ZonedDateTime, not this interface.

A ChronoZonedDateTime is the abstract representation of an offset date-time
where the Chronology chronology, or calendar system, is pluggable.
The date-time is defined in terms of fields expressed by TemporalField,
where most common implementations are defined in ChronoField.
The chronology defines how the calendar system operates and the meaning of
the standard fields.

When to use this interface
The design of the API encourages the use of ZonedDateTime rather than this
interface, even in the case where the application needs to deal with multiple
calendar systems. The rationale for this is explored in detail in ChronoLocalDate.

Ensure that the discussion in ChronoLocalDate has been read and understood
before using this interface.

An era of the time-line.

Most calendar systems have a single epoch dividing the time-line into two eras.
However, some calendar systems, have multiple eras, such as one for the reign
of each leader.
In all cases, the era is conceptually the largest division of the time-line.
Each chronology defines the Era's that are known Eras and a
Chronology.eras to get the valid eras.

For example, the Thai Buddhist calendar system divides time into two eras,
before and after a single date. By contrast, the Japanese calendar system
has one era for the reign of each Emperor.

Instances of Era may be compared using the == operator.

 Locale locale = Locale.forLanguageTag("en-US-u-ca-islamic-umalqura");
 Chronology chrono = Chronology.ofLocale(locale);

The Hijrah calendar is a lunar calendar supporting Islamic calendars.

The HijrahChronology follows the rules of the Hijrah calendar system. The Hijrah
calendar has several variants based on differences in when the new moon is
determined to have occurred and where the observation is made.
In some variants the length of each month is
computed algorithmically from the astronomical data for the moon and earth and
in others the length of the month is determined by an authorized sighting
of the new moon. For the algorithmically based calendars the calendar
can project into the future.
For sighting based calendars only historical data from past
sightings is available.

The length of each month is 29 or 30 days.
Ordinary years have 354 days; leap years have 355 days.


CLDR and LDML identify variants:



Chronology ID
Calendar Type
Locale extension, see Locale
Description




Hijrah-umalqura
islamic-umalqura
ca-islamic-umalqura
Islamic - Umm Al-Qura calendar of Saudi Arabia



Additional variants may be available through Chronology.getAvailableChronologies().

Example

Selecting the chronology from the locale uses Chronology.ofLocale(java.util.Locale)
to find the Chronology based on Locale supported BCP 47 extension mechanism
to request a specific calendar ("ca"). For example,



     Locale locale = Locale.forLanguageTag("en-US-u-ca-islamic-umalqura");
     Chronology chrono = Chronology.ofLocale(locale);

A date in the Hijrah calendar system.

This date operates using one of several variants of the
java.time.chrono.Hijrah calendar.

The Hijrah calendar has a different total of days in a year than
Gregorian calendar, and the length of each month is based on the period
of a complete revolution of the moon around the earth
(as between successive new moons).
Refer to the HijrahChronology for details of supported variants.

Each HijrahDate is created bound to a particular HijrahChronology,
The same chronology is propagated to each HijrahDate computed from the date.
To use a different Hijrah variant, its HijrahChronology can be used
to create new HijrahDate instances.
Alternatively, the withVariant(java.time.chrono.HijrahChronology) method can be used to convert
to a new HijrahChronology.


This is a value-based
class; use of identity-sensitive operations (including reference equality
(==), identity hash code, or synchronization) on instances of
HijrahDate may have unpredictable results and should be avoided.
The equals method should be used for comparisons.

The ISO calendar system.

This chronology defines the rules of the ISO calendar system.
This calendar system is based on the ISO-8601 standard, which is the
de facto world calendar.

The fields are defined as follows:

era - There are two eras, 'Current Era' (CE) and 'Before Current Era' (BCE).
year-of-era - The year-of-era is the same as the proleptic-year for the current CE era.
 For the BCE era before the ISO epoch the year increases from 1 upwards as time goes backwards.
proleptic-year - The proleptic year is the same as the year-of-era for the
 current era. For the previous era, years have zero, then negative values.
month-of-year - There are 12 months in an ISO year, numbered from 1 to 12.
day-of-month - There are between 28 and 31 days in each of the ISO month, numbered from 1 to 31.
 Months 4, 6, 9 and 11 have 30 days, Months 1, 3, 5, 7, 8, 10 and 12 have 31 days.
 Month 2 has 28 days, or 29 in a leap year.
day-of-year - There are 365 days in a standard ISO year and 366 in a leap year.
 The days are numbered from 1 to 365 or 1 to 366.
leap-year - Leap years occur every 4 years, except where the year is divisble by 100 and not divisble by 400.

The Japanese Imperial calendar system.

This chronology defines the rules of the Japanese Imperial calendar system.
This calendar system is primarily used in Japan.
The Japanese Imperial calendar system is the same as the ISO calendar system
apart from the era-based year numbering.

Japan introduced the Gregorian calendar starting with Meiji 6.
Only Meiji and later eras are supported;
dates before Meiji 6, January 1 are not supported.

The supported ChronoField instances are:

DAY_OF_WEEK
DAY_OF_MONTH
DAY_OF_YEAR
EPOCH_DAY
MONTH_OF_YEAR
PROLEPTIC_MONTH
YEAR_OF_ERA
YEAR
ERA

A date in the Japanese Imperial calendar system.

This date operates using the java.time.chrono.Japanese Imperial calendar.
This calendar system is primarily used in Japan.

The Japanese Imperial calendar system is the same as the ISO calendar system
apart from the era-based year numbering. The proleptic-year is defined to be
equal to the ISO proleptic-year.

Japan introduced the Gregorian calendar starting with Meiji 6.
Only Meiji and later eras are supported;
dates before Meiji 6, January 1 are not supported.

For example, the Japanese year "Heisei 24" corresponds to ISO year "2012".
Calling japaneseDate.get(YEAR_OF_ERA) will return 24.
Calling japaneseDate.get(YEAR) will return 2012.
Calling japaneseDate.get(ERA) will return 2, corresponding to
JapaneseChronology.ERA_HEISEI.


This is a value-based
class; use of identity-sensitive operations (including reference equality
(==), identity hash code, or synchronization) on instances of
JapaneseDate may have unpredictable results and should be avoided.
The equals method should be used for comparisons.

An era in the Japanese Imperial calendar system.

The Japanese government defines the official name and start date of
each era. Eras are consecutive and their date ranges do not overlap,
so the end date of one era is always the day before the start date
of the next era.

The Java SE Platform supports all eras defined by the Japanese government,
beginning with the Meiji era. Each era is identified in the Platform by an
integer value and a name. The of(int) and valueOf(String)
methods may be used to obtain a singleton instance of JapaneseEra for each
era. The values() method returns the singleton instances of all
supported eras.

For convenience, this class declares a number of public static final fields
that refer to singleton instances returned by the values() method.

The Minguo calendar system.

This chronology defines the rules of the Minguo calendar system.
This calendar system is primarily used in the Republic of China, often known as Taiwan.
Dates are aligned such that 0001-01-01 (Minguo) is 1912-01-01 (ISO).

The fields are defined as follows:

era - There are two eras, the current 'Republic' (ERA_ROC) and the previous era (ERA_BEFORE_ROC).
year-of-era - The year-of-era for the current era increases uniformly from the epoch at year one.
 For the previous era the year increases from one as time goes backwards.
 The value for the current era is equal to the ISO proleptic-year minus 1911.
proleptic-year - The proleptic year is the same as the year-of-era for the
 current era. For the previous era, years have zero, then negative values.
 The value is equal to the ISO proleptic-year minus 1911.
month-of-year - The Minguo month-of-year exactly matches ISO.
day-of-month - The Minguo day-of-month exactly matches ISO.
day-of-year - The Minguo day-of-year exactly matches ISO.
leap-year - The Minguo leap-year pattern exactly matches ISO, such that the two calendars
 are never out of step.

A date in the Minguo calendar system.

This date operates using the java.time.chrono.Minguo calendar.
This calendar system is primarily used in the Republic of China, often known as Taiwan.
Dates are aligned such that 0001-01-01 (Minguo) is 1912-01-01 (ISO).


This is a value-based
class; use of identity-sensitive operations (including reference equality
(==), identity hash code, or synchronization) on instances of
MinguoDate may have unpredictable results and should be avoided.
The equals method should be used for comparisons.

The Thai Buddhist calendar system.

This chronology defines the rules of the Thai Buddhist calendar system.
This calendar system is primarily used in Thailand.
Dates are aligned such that 2484-01-01 (Buddhist) is 1941-01-01 (ISO).

The fields are defined as follows:

era - There are two eras, the current 'Buddhist' (ERA_BE) and the previous era (ERA_BEFORE_BE).
year-of-era - The year-of-era for the current era increases uniformly from the epoch at year one.
 For the previous era the year increases from one as time goes backwards.
 The value for the current era is equal to the ISO proleptic-year plus 543.
proleptic-year - The proleptic year is the same as the year-of-era for the
 current era. For the previous era, years have zero, then negative values.
 The value is equal to the ISO proleptic-year plus 543.
month-of-year - The ThaiBuddhist month-of-year exactly matches ISO.
day-of-month - The ThaiBuddhist day-of-month exactly matches ISO.
day-of-year - The ThaiBuddhist day-of-year exactly matches ISO.
leap-year - The ThaiBuddhist leap-year pattern exactly matches ISO, such that the two calendars
 are never out of step.

A date in the Thai Buddhist calendar system.

This date operates using the java.time.chrono.Thai Buddhist calendar.
This calendar system is primarily used in Thailand.
Dates are aligned such that 2484-01-01 (Buddhist) is 1941-01-01 (ISO).


This is a value-based
class; use of identity-sensitive operations (including reference equality
(==), identity hash code, or synchronization) on instances of
ThaiBuddhistDate may have unpredictable results and should be avoided.
The equals method should be used for comparisons.