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.

A clock providing access to the current instant, date and time using a time-zone.

Instances of this class are used to find the current instant, which can be
interpreted using the stored time-zone to find the current date and time.
As such, a clock can be used instead of System.currentTimeMillis()
and TimeZone.getDefault().

Use of a Clock is optional. All key date-time classes also have a
now() factory method that uses the system clock in the default time zone.
The primary purpose of this abstraction is to allow alternate clocks to be
plugged in as and when required. Applications use an object to obtain the
current time rather than a static method. This can simplify testing.

Best practice for applications is to pass a Clock into any method
that requires the current instant. A dependency injection framework is one
way to achieve this:


 public class MyBean {
   private Clock clock;  // dependency inject
   ...
   public void process(LocalDate eventDate) {
     if (eventDate.isBefore(LocalDate.now(clock)) {
       ...
     }
   }
 }
This approach allows an alternate clock, such as fixed
or offset to be used during testing.

The system factory methods provide clocks based on the best available
system clock This may use System.currentTimeMillis(), or a higher
resolution clock if one is available.

Exception used to indicate a problem while calculating a date-time.

This exception is used to indicate problems with creating, querying
and manipulating date-time objects.

A time-based amount of time, such as '34.5 seconds'.

This class models a quantity or amount of time in terms of seconds and nanoseconds.
It can be accessed using other duration-based units, such as minutes and hours.
In addition, the DAYS unit can be used and is treated as
exactly equal to 24 hours, thus ignoring daylight savings effects.
See Period for the date-based equivalent to this class.

A physical duration could be of infinite length.
For practicality, the duration is stored with constraints similar to Instant.
The duration uses nanosecond resolution with a maximum value of the seconds that can
be held in a long. This is greater than the current estimated age of the universe.

The range of a duration requires the storage of a number larger than a long.
To achieve this, the class stores a long representing seconds and an int
representing nanosecond-of-second, which will always be between 0 and 999,999,999.
The model is of a directed duration, meaning that the duration may be negative.

The duration is measured in "seconds", but these are not necessarily identical to
the scientific "SI second" definition based on atomic clocks.
This difference only impacts durations measured near a leap-second and should not affect
most applications.
See Instant for a discussion as to the meaning of the second and time-scales.


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

Formatter for printing and parsing date-time objects.

This class provides the main application entry point for printing and parsing
and provides common implementations of DateTimeFormatter:

Using predefined constants, such as ISO_LOCAL_DATE
Using pattern letters, such as uuuu-MMM-dd
Using localized styles, such as long or medium


More complex formatters are provided by
DateTimeFormatterBuilder.


The main date-time classes provide two methods - one for formatting,
format(DateTimeFormatter formatter), and one for parsing,
parse(CharSequence text, DateTimeFormatter formatter).
For example:


 LocalDate date = LocalDate.now();
 String text = date.format(formatter);
 LocalDate parsedDate = LocalDate.parse(text, formatter);

In addition to the format, formatters can be created with desired Locale,
Chronology, ZoneId, and DecimalStyle.

The withLocale method returns a new formatter that
overrides the locale. The locale affects some aspects of formatting and
parsing. For example, the ofLocalizedDate provides a
formatter that uses the locale specific date format.

The withChronology method returns a new formatter
that overrides the chronology. If overridden, the date-time value is
converted to the chronology before formatting. During parsing the date-time
value is converted to the chronology before it is returned.

The withZone method returns a new formatter that overrides
the zone. If overridden, the date-time value is converted to a ZonedDateTime
with the requested ZoneId before formatting. During parsing the ZoneId is
applied before the value is returned.

The withDecimalStyle method returns a new formatter that
overrides the DecimalStyle. The DecimalStyle symbols are used for
formatting and parsing.

Some applications may need to use the older java.text.Format
class for formatting. The toFormat() method returns an
implementation of java.text.Format.

Predefined Formatters



Formatter
Description
Example




ofLocalizedDate(dateStyle)
 Formatter with date style from the locale
 '2011-12-03'


 ofLocalizedTime(timeStyle)
 Formatter with time style from the locale
 '10:15:30'


 ofLocalizedDateTime(dateTimeStyle)
 Formatter with a style for date and time from the locale
 '3 Jun 2008 11:05:30'


 ofLocalizedDateTime(dateStyle,timeStyle)

 Formatter with date and time styles from the locale
 '3 Jun 2008 11:05'


 BASIC_ISO_DATE
Basic ISO date  '20111203'


 ISO_LOCAL_DATE
 ISO Local Date
'2011-12-03'


 ISO_OFFSET_DATE
 ISO Date with offset
'2011-12-03+01:00'


 ISO_DATE
 ISO Date with or without offset
 '2011-12-03+01:00'; '2011-12-03'


 ISO_LOCAL_TIME
 Time without offset
'10:15:30'


 ISO_OFFSET_TIME
 Time with offset
'10:15:30+01:00'


 ISO_TIME
 Time with or without offset
'10:15:30+01:00'; '10:15:30'


 ISO_LOCAL_DATE_TIME
 ISO Local Date and Time
'2011-12-03T10:15:30'


 ISO_OFFSET_DATE_TIME
 Date Time with Offset
2011-12-03T10:15:30+01:00'


 ISO_ZONED_DATE_TIME
 Zoned Date Time
'2011-12-03T10:15:30+01:00[Europe/Paris]'


 ISO_DATE_TIME
 Date and time with ZoneId
'2011-12-03T10:15:30+01:00[Europe/Paris]'


 ISO_ORDINAL_DATE
 Year and day of year
'2012-337'


 ISO_WEEK_DATE
 Year and Week
2012-W48-6'

 ISO_INSTANT
 Date and Time of an Instant
'2011-12-03T10:15:30Z'


 RFC_1123_DATE_TIME
 RFC 1123 / RFC 822
'Tue, 3 Jun 2008 11:05:30 GMT'




Patterns for Formatting and Parsing
Patterns are based on a simple sequence of letters and symbols.
A pattern is used to create a Formatter using the
ofPattern(String) and ofPattern(String, Locale) methods.
For example,
"d MMM uuuu" will format 2011-12-03 as '3 Dec 2011'.
A formatter created from a pattern can be used as many times as necessary,
it is immutable and is thread-safe.

For example:


 LocalDate date = LocalDate.now();
 DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
 String text = date.format(formatter);
 LocalDate parsedDate = LocalDate.parse(text, formatter);

All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The
following pattern letters are defined:


 Symbol  Meaning                     Presentation      Examples
 ------  -------                     ------------      -------
  G       era                         text              AD; Anno Domini; A
  u       year                        year              2004; 04
  y       year-of-era                 year              2004; 04
  D       day-of-year                 number            189
  M/L     month-of-year               number/text       7; 07; Jul; July; J
  d       day-of-month                number            10

  Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter
  Y       week-based-year             year              1996; 96
  w       week-of-week-based-year     number            27
  W       week-of-month               number            4
  E       day-of-week                 text              Tue; Tuesday; T
  e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T
  F       week-of-month               number            3

  a       am-pm-of-day                text              PM
  h       clock-hour-of-am-pm (1-12)  number            12
  K       hour-of-am-pm (0-11)        number            0
  k       clock-hour-of-am-pm (1-24)  number            0

  H       hour-of-day (0-23)          number            0
  m       minute-of-hour              number            30
  s       second-of-minute            number            55
  S       fraction-of-second          fraction          978
  A       milli-of-day                number            1234
  n       nano-of-second              number            987654321
  N       nano-of-day                 number            1234000000

  V       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30
  z       time-zone name              zone-name         Pacific Standard Time; PST
  O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00;
  X       zone-offset 'Z' for zero    offset-X          Z; -08; -0830; -08:30; -083015; -08:30:15;
  x       zone-offset                 offset-x          0000; -08; -0830; -08:30; -083015; -08:30:15;
  Z       zone-offset                 offset-Z          0000; -0800; -08:00;

  p       pad next                    pad modifier      1

  '       escape for text             delimiter
  ''      single quote                literal           '
  [       optional section start
  ]       optional section end
  #       reserved for future use
  {       reserved for future use
  }       reserved for future use

The count of pattern letters determines the format.

Text: The text style is determined based on the number of pattern
letters used. Less than 4 pattern letters will use the
short form. Exactly 4 pattern letters will use the
full form. Exactly 5 pattern letters will use the
narrow form.
Pattern letters 'L', 'c', and 'q' specify the stand-alone form of the text styles.

Number: If the count of letters is one, then the value is output using
the minimum number of digits and without padding. Otherwise, the count of digits
is used as the width of the output field, with the value zero-padded as necessary.
The following pattern letters have constraints on the count of letters.
Only one letter of 'c' and 'F' can be specified.
Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified.
Up to three letters of 'D' can be specified.

Number/Text: If the count of pattern letters is 3 or greater, use the
Text rules above. Otherwise use the Number rules above.

Fraction: Outputs the nano-of-second field as a fraction-of-second.
The nano-of-second value has nine digits, thus the count of pattern letters
is from 1 to 9. If it is less than 9, then the nano-of-second value is
truncated, with only the most significant digits being output.

Year: The count of letters determines the minimum field width below
which padding is used. If the count of letters is two, then a
reduced two digit form is
used. For printing, this outputs the rightmost two digits. For parsing, this
will parse using the base value of 2000, resulting in a year within the range
2000 to 2099 inclusive. If the count of letters is less than four (but not
two), then the sign is only output for negative years as per
SignStyle.NORMAL. Otherwise, the sign is output if the pad width is
exceeded, as per SignStyle.EXCEEDS_PAD.

ZoneId: This outputs the time-zone ID, such as 'Europe/Paris'. If the
count of letters is two, then the time-zone ID is output. Any other count of
letters throws IllegalArgumentException.

Zone names: This outputs the display name of the time-zone ID. If the
count of letters is one, two or three, then the short name is output. If the
count of letters is four, then the full name is output. Five or more letters
throws IllegalArgumentException.

Offset X and x: This formats the offset based on the number of pattern
letters. One letter outputs just the hour, such as '+01', unless the minute
is non-zero in which case the minute is also output, such as '+0130'. Two
letters outputs the hour and minute, without a colon, such as '+0130'. Three
letters outputs the hour and minute, with a colon, such as '+01:30'. Four
letters outputs the hour and minute and optional second, without a colon,
such as '+013015'. Five letters outputs the hour and minute and optional
second, with a colon, such as '+01:30:15'. Six or more letters throws
IllegalArgumentException. Pattern letter 'X' (upper case) will output
'Z' when the offset to be output would be zero, whereas pattern letter 'x'
(lower case) will output '+00', '+0000', or '+00:00'.

Offset O: This formats the localized offset based on the number of
pattern letters. One letter outputs the short
form of the localized offset, which is localized offset text, such as 'GMT',
with hour without leading zero, optional 2-digit minute and second if
non-zero, and colon, for example 'GMT+8'. Four letters outputs the
full form, which is localized offset text,
such as 'GMT, with 2-digit hour and minute field, optional second field
if non-zero, and colon, for example 'GMT+08:00'. Any other count of letters
throws IllegalArgumentException.

Offset Z: This formats the offset based on the number of pattern
letters. One, two or three letters outputs the hour and minute, without a
colon, such as '+0130'. The output will be '+0000' when the offset is zero.
Four letters outputs the full form of localized
offset, equivalent to four letters of Offset-O. The output will be the
corresponding localized offset text if the offset is zero. Five
letters outputs the hour, minute, with optional second if non-zero, with
colon. It outputs 'Z' if the offset is zero.
Six or more letters throws IllegalArgumentException.

Optional section: The optional section markers work exactly like
calling DateTimeFormatterBuilder.optionalStart() and
DateTimeFormatterBuilder.optionalEnd().

Pad modifier: Modifies the pattern that immediately follows to be
padded with spaces. The pad width is determined by the number of pattern
letters. This is the same as calling
DateTimeFormatterBuilder.padNext(int).

For example, 'ppH' outputs the hour-of-day padded on the left with spaces to
a width of 2.

Any unrecognized letter is an error. Any non-letter character, other than
'[', ']', '{', '}', '#' and the single quote will be output directly.
Despite this, it is recommended to use single quotes around all characters
that you want to output directly to ensure that future changes do not break
your application.

Resolving
Parsing is implemented as a two-phase operation.
First, the text is parsed using the layout defined by the formatter, producing
a Map of field to value, a ZoneId and a Chronology.
Second, the parsed data is resolved, by validating, combining and
simplifying the various fields into more useful ones.

Five parsing methods are supplied by this class.
Four of these perform both the parse and resolve phases.
The fifth method, parseUnresolved(CharSequence, ParsePosition),
only performs the first phase, leaving the result unresolved.
As such, it is essentially a low-level operation.

The resolve phase is controlled by two parameters, set on this class.

The ResolverStyle is an enum that offers three different approaches,
strict, smart and lenient. The smart option is the default.
It can be set using withResolverStyle(ResolverStyle).

The withResolverFields(TemporalField...) parameter allows the
set of fields that will be resolved to be filtered before resolving starts.
For example, if the formatter has parsed a year, month, day-of-month
and day-of-year, then there are two approaches to resolve a date:
(year  month  day-of-month) and (year  day-of-year).
The resolver fields allows one of the two approaches to be selected.
If no resolver fields are set then both approaches must result in the same date.

Resolving separate fields to form a complete date and time is a complex
process with behaviour distributed across a number of classes.
It follows these steps:

The chronology is determined.
The chronology of the result is either the chronology that was parsed,
or if no chronology was parsed, it is the chronology set on this class,
or if that is null, it is IsoChronology.
The ChronoField date fields are resolved.
This is achieved using Chronology.resolveDate(Map, ResolverStyle).
Documentation about field resolution is located in the implementation
of Chronology.
The ChronoField time fields are resolved.
This is documented on ChronoField and is the same for all chronologies.
Any fields that are not ChronoField are processed.
This is achieved using TemporalField.resolve(Map, TemporalAccessor, ResolverStyle).
Documentation about field resolution is located in the implementation
of TemporalField.
The ChronoField date and time fields are re-resolved.
This allows fields in step four to produce ChronoField values
and have them be processed into dates and times.
A LocalTime is formed if there is at least an hour-of-day available.
This involves providing default values for minute, second and fraction of second.
Any remaining unresolved fields are cross-checked against any
date and/or time that was resolved. Thus, an earlier stage would resolve
(year  month  day-of-month) to a date, and this stage would check that
day-of-week was valid for the date.
If an excess number of days
was parsed then it is added to the date if a date is available.

Builder to create date-time formatters.

This allows a DateTimeFormatter to be created.
All date-time formatters are created ultimately using this builder.

The basic elements of date-time can all be added:

Value - a numeric value
Fraction - a fractional value including the decimal place. Always use this when
outputting fractions to ensure that the fraction is parsed correctly
Text - the textual equivalent for the value
OffsetId/Offset - the java.time.zone offset
ZoneId - the java.time.time-zone id
ZoneText - the name of the time-zone
ChronologyId - the java.time.chrono.chronology id
ChronologyText - the name of the chronology
Literal - a text literal
Nested and Optional - formats can be nested or made optional

In addition, any of the elements may be decorated by padding, either with spaces or any other character.

Finally, a shorthand pattern, mostly compatible with java.text.SimpleDateFormat SimpleDateFormat
can be used, see appendPattern(String).
In practice, this simply parses the pattern and calls other methods on the builder.

An exception thrown when an error occurs during parsing.

This exception includes the text being parsed and the error index.

Localized decimal style used in date and time formatting.

A significant part of dealing with dates and times is the localization.
This class acts as a central point for accessing the information.

An instantaneous point on the time-line.

This class models a single instantaneous point on the time-line.
This might be used to record event time-stamps in the application.

The range of an instant requires the storage of a number larger than a long.
To achieve this, the class stores a long representing epoch-seconds and an
int representing nanosecond-of-second, which will always be between 0 and 999,999,999.
The epoch-seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z
where instants after the epoch have positive values, and earlier instants have negative values.
For both the epoch-second and nanosecond parts, a larger value is always later on the time-line
than a smaller value.

Time-scale

The length of the solar day is the standard way that humans measure time.
This has traditionally been subdivided into 24 hours of 60 minutes of 60 seconds,
forming a 86400 second day.

Modern timekeeping is based on atomic clocks which precisely define an SI second
relative to the transitions of a Caesium atom. The length of an SI second was defined
to be very close to the 86400th fraction of a day.

Unfortunately, as the Earth rotates the length of the day varies.
In addition, over time the average length of the day is getting longer as the Earth slows.
As a result, the length of a solar day in 2012 is slightly longer than 86400 SI seconds.
The actual length of any given day and the amount by which the Earth is slowing
are not predictable and can only be determined by measurement.
The UT1 time-scale captures the accurate length of day, but is only available some
time after the day has completed.

The UTC time-scale is a standard approach to bundle up all the additional fractions
of a second from UT1 into whole seconds, known as leap-seconds.
A leap-second may be added or removed depending on the Earth's rotational changes.
As such, UTC permits a day to have 86399 SI seconds or 86401 SI seconds where
necessary in order to keep the day aligned with the Sun.

The modern UTC time-scale was introduced in 1972, introducing the concept of whole leap-seconds.
Between 1958 and 1972, the definition of UTC was complex, with minor sub-second leaps and
alterations to the length of the notional second. As of 2012, discussions are underway
to change the definition of UTC again, with the potential to remove leap seconds or
introduce other changes.

Given the complexity of accurate timekeeping described above, this Java API defines
its own time-scale, the Java Time-Scale.

The Java Time-Scale divides each calendar day into exactly 86400
subdivisions, known as seconds.  These seconds may differ from the
SI second.  It closely matches the de facto international civil time
scale, the definition of which changes from time to time.

The Java Time-Scale has slightly different definitions for different
segments of the time-line, each based on the consensus international
time scale that is used as the basis for civil time. Whenever the
internationally-agreed time scale is modified or replaced, a new
segment of the Java Time-Scale must be defined for it.  Each segment
must meet these requirements:

the Java Time-Scale shall closely match the underlying international
 civil time scale;
the Java Time-Scale shall exactly match the international civil
 time scale at noon each day;
the Java Time-Scale shall have a precisely-defined relationship to
 the international civil time scale.

There are currently, as of 2013, two segments in the Java time-scale.

For the segment from 1972-11-03 (exact boundary discussed below) until
further notice, the consensus international time scale is UTC (with
leap seconds).  In this segment, the Java Time-Scale is identical to
UTC-SLS.
This is identical to UTC on days that do not have a leap second.
On days that do have a leap second, the leap second is spread equally
over the last 1000 seconds of the day, maintaining the appearance of
exactly 86400 seconds per day.

For the segment prior to 1972-11-03, extending back arbitrarily far,
the consensus international time scale is defined to be UT1, applied
proleptically, which is equivalent to the (mean) solar time on the
prime meridian (Greenwich). In this segment, the Java Time-Scale is
identical to the consensus international time scale. The exact
boundary between the two segments is the instant where UT1 = UTC
between 1972-11-03T00:00 and 1972-11-04T12:00.

Implementations of the Java time-scale using the JSR-310 API are not
required to provide any clock that is sub-second accurate, or that
progresses monotonically or smoothly. Implementations are therefore
not required to actually perform the UTC-SLS slew or to otherwise be
aware of leap seconds. JSR-310 does, however, require that
implementations must document the approach they use when defining a
clock representing the current instant.
See Clock for details on the available clocks.

The Java time-scale is used for all date-time classes.
This includes Instant, LocalDate, LocalTime, OffsetDateTime,
ZonedDateTime and Duration.


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

A date without a time-zone in the ISO-8601 calendar system,
such as 2007-12-03.

LocalDate is an immutable date-time object that represents a date,
often viewed as year-month-day. Other date fields, such as day-of-year,
day-of-week and week-of-year, can also be accessed.
For example, the value "2nd October 2007" can be stored in a LocalDate.

This class does not store or represent a time or time-zone.
Instead, it is a description of the date, as used for birthdays.
It cannot represent an instant on the time-line without additional information
such as an offset or time-zone.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which today's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
However, any application that makes use of historical dates, and requires them
to be accurate will find the ISO-8601 approach unsuitable.


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

A date-time without a time-zone in the ISO-8601 calendar system,
such as 2007-12-03T10:15:30.

LocalDateTime is an immutable date-time object that represents a date-time,
often viewed as year-month-day-hour-minute-second. Other date and time fields,
such as day-of-year, day-of-week and week-of-year, can also be accessed.
Time is represented to nanosecond precision.
For example, the value "2nd October 2007 at 13:45.30.123456789" can be
stored in a LocalDateTime.

This class does not store or represent a time-zone.
Instead, it is a description of the date, as used for birthdays, combined with
the local time as seen on a wall clock.
It cannot represent an instant on the time-line without additional information
such as an offset or time-zone.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which today's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
However, any application that makes use of historical dates, and requires them
to be accurate will find the ISO-8601 approach unsuitable.


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

A time without a time-zone in the ISO-8601 calendar system,
such as 10:15:30.

LocalTime is an immutable date-time object that represents a time,
often viewed as hour-minute-second.
Time is represented to nanosecond precision.
For example, the value "13:45.30.123456789" can be stored in a LocalTime.

This class does not store or represent a date or time-zone.
Instead, it is a description of the local time as seen on a wall clock.
It cannot represent an instant on the time-line without additional information
such as an offset or time-zone.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. This API assumes that all calendar systems use the same
representation, this class, for time-of-day.


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

A month-day in the ISO-8601 calendar system, such as --12-03.

MonthDay is an immutable date-time object that represents the combination
of a month and day-of-month. Any field that can be derived from a month and day,
such as quarter-of-year, can be obtained.

This class does not store or represent a year, time or time-zone.
For example, the value "December 3rd" can be stored in a MonthDay.

Since a MonthDay does not possess a year, the leap day of
February 29th is considered valid.

This class implements TemporalAccessor rather than Temporal.
This is because it is not possible to define whether February 29th is valid or not
without external information, preventing the implementation of plus/minus.
Related to this, MonthDay only provides access to query and set the fields
MONTH_OF_YEAR and DAY_OF_MONTH.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which today's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
However, any application that makes use of historical dates, and requires them
to be accurate will find the ISO-8601 approach unsuitable.


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

A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system,
such as 2007-12-03T10:15:30+01:00.

OffsetDateTime is an immutable representation of a date-time with an offset.
This class stores all date and time fields, to a precision of nanoseconds,
as well as the offset from UTC/Greenwich. For example, the value
"2nd October 2007 at 13:45.30.123456789 02:00" can be stored in an OffsetDateTime.

OffsetDateTime, ZonedDateTime and Instant all store an instant
on the time-line to nanosecond precision.
Instant is the simplest, simply representing the instant.
OffsetDateTime adds to the instant the offset from UTC/Greenwich, which allows
the local date-time to be obtained.
ZonedDateTime adds full time-zone rules.

It is intended that ZonedDateTime or Instant is used to model data
in simpler applications. This class may be used when modeling date-time concepts in
more detail, or when communicating to a database or in a network protocol.


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

A time with an offset from UTC/Greenwich in the ISO-8601 calendar system,
such as 10:15:30+01:00.

OffsetTime is an immutable date-time object that represents a time, often
viewed as hour-minute-second-offset.
This class stores all time fields, to a precision of nanoseconds,
as well as a zone offset.
For example, the value "13:45.30.123456789+02:00" can be stored
in an OffsetTime.


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

A date-based amount of time in the ISO-8601 calendar system,
such as '2 years, 3 months and 4 days'.

This class models a quantity or amount of time in terms of years, months and days.
See Duration for the time-based equivalent to this class.

Durations and periods differ in their treatment of daylight savings time
when added to ZonedDateTime. A Duration will add an exact
number of seconds, thus a duration of one day is always exactly 24 hours.
By contrast, a Period will add a conceptual day, trying to maintain
the local time.

For example, consider adding a period of one day and a duration of one day to
18:00 on the evening before a daylight savings gap. The Period will add
the conceptual day and result in a ZonedDateTime at 18:00 the following day.
By contrast, the Duration will add exactly 24 hours, resulting in a
ZonedDateTime at 19:00 the following day (assuming a one hour DST gap).

The supported units of a period are YEARS,
MONTHS and DAYS.
All three fields are always present, but may be set to zero.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which today's rules for leap years are applied for all time.

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


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

Fields and units specific to the ISO-8601 calendar system,
including quarter-of-year and week-based-year.

This class defines fields and units that are specific to the ISO calendar system.

Quarter of year
The ISO-8601 standard is based on the standard civic 12 month year.
This is commonly divided into four quarters, often abbreviated as Q1, Q2, Q3 and Q4.

January, February and March are in Q1.
April, May and June are in Q2.
July, August and September are in Q3.
October, November and December are in Q4.

The complete date is expressed using three fields:

DAY_OF_QUARTER - the day within the quarter, from 1 to 90, 91 or 92
QUARTER_OF_YEAR - the week within the week-based-year
YEAR - the standard ISO year


Week based years
The ISO-8601 standard was originally intended as a data interchange format,
defining a string format for dates and times. However, it also defines an
alternate way of expressing the date, based on the concept of week-based-year.

The date is expressed using three fields:

DAY_OF_WEEK - the standard field defining the
 day-of-week from Monday (1) to Sunday (7)
WEEK_OF_WEEK_BASED_YEAR - the week within the week-based-year
WEEK_BASED_YEAR - the week-based-year

The week-based-year itself is defined relative to the standard ISO proleptic year.
It differs from the standard year in that it always starts on a Monday.

The first week of a week-based-year is the first Monday-based week of the standard
ISO year that has at least 4 days in the new year.

If January 1st is Monday then week 1 starts on January 1st
If January 1st is Tuesday then week 1 starts on December 31st of the previous standard year
If January 1st is Wednesday then week 1 starts on December 30th of the previous standard year
If January 1st is Thursday then week 1 starts on December 29th of the previous standard year
If January 1st is Friday then week 1 starts on January 4th
If January 1st is Saturday then week 1 starts on January 3rd
If January 1st is Sunday then week 1 starts on January 2nd

There are 52 weeks in most week-based years, however on occasion there are 53 weeks.

For example:


Examples of Week based Years
DateDay-of-weekField values
2008-12-28SundayWeek 52 of week-based-year 2008
2008-12-29MondayWeek 1 of week-based-year 2009
2008-12-31WednesdayWeek 1 of week-based-year 2009
2009-01-01ThursdayWeek 1 of week-based-year 2009
2009-01-04SundayWeek 1 of week-based-year 2009
2009-01-05MondayWeek 2 of week-based-year 2009

A set of date fields that provide access to Julian Days.

The Julian Day is a standard way of expressing date and time commonly used in the scientific community.
It is expressed as a decimal number of whole days where days start at midday.
This class represents variations on Julian Days that count whole days from midnight.

The fields are implemented relative to EPOCH_DAY.
The fields are supported, and can be queried and set if EPOCH_DAY is available.
The fields work with all chronologies.

Framework-level interface defining read-write access to a temporal object,
such as a date, time, offset or some combination of these.

This is the base interface type for date, time and offset objects that
are complete enough to be manipulated using plus and minus.
It is implemented by those classes that can provide and manipulate information
as java.time.temporal.fields or java.time.temporal.queries.
See TemporalAccessor for the read-only version of this interface.

Most date and time information can be represented as a number.
These are modeled using TemporalField with the number held using
a long to handle large values. Year, month and day-of-month are
simple examples of fields, but they also include instant and offsets.
See ChronoField for the standard set of fields.

Two pieces of date/time information cannot be represented by numbers,
the java.time.chrono.chronology and the
java.time.time-zone.
These can be accessed via queries using
the static methods defined on TemporalQuery.

This interface is a framework-level interface that should not be widely
used in application code. Instead, applications should create and pass
around instances of concrete types, such as LocalDate.
There are many reasons for this, part of which is that implementations
of this interface may be in calendar systems other than ISO.
See ChronoLocalDate for a fuller discussion of the issues.

When to implement

A class should implement this interface if it meets three criteria:

it provides access to date/time/offset information, as per TemporalAccessor
the set of fields are contiguous from the largest to the smallest
the set of fields are complete, such that no other field is needed to define the
 valid range of values for the fields that are represented


Four examples make this clear:

LocalDate implements this interface as it represents a set of fields
 that are contiguous from days to forever and require no external information to determine
 the validity of each date. It is therefore able to implement plus/minus correctly.
LocalTime implements this interface as it represents a set of fields
 that are contiguous from nanos to within days and require no external information to determine
 validity. It is able to implement plus/minus correctly, by wrapping around the day.
MonthDay, the combination of month-of-year and day-of-month, does not implement
 this interface.  While the combination is contiguous, from days to months within years,
 the combination does not have sufficient information to define the valid range of values
 for day-of-month.  As such, it is unable to implement plus/minus correctly.
The combination day-of-week and day-of-month ("Friday the 13th") should not implement
 this interface. It does not represent a contiguous set of fields, as days to weeks overlaps
 days to months.

Framework-level interface defining read-only access to a temporal object,
such as a date, time, offset or some combination of these.

This is the base interface type for date, time and offset objects.
It is implemented by those classes that can provide information
as java.time.temporal.fields or java.time.temporal.queries.

Most date and time information can be represented as a number.
These are modeled using TemporalField with the number held using
a long to handle large values. Year, month and day-of-month are
simple examples of fields, but they also include instant and offsets.
See ChronoField for the standard set of fields.

Two pieces of date/time information cannot be represented by numbers,
the java.time.chrono.chronology and the
java.time.time-zone.
These can be accessed via queries using
the static methods defined on TemporalQuery.

A sub-interface, Temporal, extends this definition to one that also
supports adjustment and manipulation on more complete temporal objects.

This interface is a framework-level interface that should not be widely
used in application code. Instead, applications should create and pass
around instances of concrete types, such as LocalDate.
There are many reasons for this, part of which is that implementations
of this interface may be in calendar systems other than ISO.
See ChronoLocalDate for a fuller discussion of the issues.

Strategy for adjusting a temporal object.

Adjusters are a key tool for modifying temporal objects.
They exist to externalize the process of adjustment, permitting different
approaches, as per the strategy design pattern.
Examples might be an adjuster that sets the date avoiding weekends, or one that
sets the date to the last day of the month.

There are two equivalent ways of using a TemporalAdjuster.
The first is to invoke the method on this interface directly.
The second is to use Temporal.with(TemporalAdjuster):


  // these two lines are equivalent, but the second approach is recommended
  temporal = thisAdjuster.adjustInto(temporal);
  temporal = temporal.with(thisAdjuster);
It is recommended to use the second approach, with(TemporalAdjuster),
as it is a lot clearer to read in code.

The TemporalAdjusters class contains a standard set of adjusters,
available as static methods.
These include:

finding the first or last day of the month
finding the first day of next month
finding the first or last day of the year
finding the first day of next year
finding the first or last day-of-week within a month, such as "first Wednesday in June"
finding the next or previous day-of-week, such as "next Thursday"

Common and useful TemporalAdjusters.

Adjusters are a key tool for modifying temporal objects.
They exist to externalize the process of adjustment, permitting different
approaches, as per the strategy design pattern.
Examples might be an adjuster that sets the date avoiding weekends, or one that
sets the date to the last day of the month.

There are two equivalent ways of using a TemporalAdjuster.
The first is to invoke the method on the interface directly.
The second is to use Temporal.with(TemporalAdjuster):


  // these two lines are equivalent, but the second approach is recommended
  temporal = thisAdjuster.adjustInto(temporal);
  temporal = temporal.with(thisAdjuster);
It is recommended to use the second approach, with(TemporalAdjuster),
as it is a lot clearer to read in code.

This class contains a standard set of adjusters, available as static methods.
These include:

finding the first or last day of the month
finding the first day of next month
finding the first or last day of the year
finding the first day of next year
finding the first or last day-of-week within a month, such as "first Wednesday in June"
finding the next or previous day-of-week, such as "next Thursday"

Framework-level interface defining an amount of time, such as
"6 hours", "8 days" or "2 years and 3 months".

This is the base interface type for amounts of time.
An amount is distinct from a date or time-of-day in that it is not tied
to any specific point on the time-line.

The amount can be thought of as a Map of TemporalUnit to
long, exposed via getUnits() and get(TemporalUnit).
A simple case might have a single unit-value pair, such as "6 hours".
A more complex case may have multiple unit-value pairs, such as
"7 years, 3 months and 5 days".

There are two common implementations.
Period is a date-based implementation, storing years, months and days.
Duration is a time-based implementation, storing seconds and nanoseconds,
but providing some access using other duration based units such as minutes,
hours and fixed 24-hour days.

This interface is a framework-level interface that should not be widely
used in application code. Instead, applications should create and pass
around instances of concrete types, such as Period and Duration.

A field of date-time, such as month-of-year or hour-of-minute.

Date and time is expressed using fields which partition the time-line into something
meaningful for humans. Implementations of this interface represent those fields.

The most commonly used units are defined in ChronoField.
Further fields are supplied in IsoFields, WeekFields and JulianFields.
Fields can also be written by application code by implementing this interface.

The field works using double dispatch. Client code calls methods on a date-time like
LocalDateTime which check if the field is a ChronoField.
If it is, then the date-time must handle it.
Otherwise, the method call is re-dispatched to the matching method in this interface.

Common implementations of TemporalQuery.

This class provides common implementations of TemporalQuery.
These are defined here as they must be constants, and the definition
of lambdas does not guarantee that. By assigning them once here,
they become 'normal' Java constants.

Queries are a key tool for extracting information from temporal objects.
They exist to externalize the process of querying, permitting different
approaches, as per the strategy design pattern.
Examples might be a query that checks if the date is the day before February 29th
in a leap year, or calculates the number of days to your next birthday.

The TemporalField interface provides another mechanism for querying
temporal objects. That interface is limited to returning a long.
By contrast, queries can return any type.

There are two equivalent ways of using a TemporalQuery.
The first is to invoke the method on this interface directly.
The second is to use TemporalAccessor.query(TemporalQuery):


  // these two lines are equivalent, but the second approach is recommended
  temporal = thisQuery.queryFrom(temporal);
  temporal = temporal.query(thisQuery);
It is recommended to use the second approach, query(TemporalQuery),
as it is a lot clearer to read in code.

The most common implementations are method references, such as
LocalDate::from and ZoneId::from.
Additional common queries are provided to return:

 a Chronology,
 a LocalDate,
 a LocalTime,
 a ZoneOffset,
 a precision,
 a zone, or
 a zoneId.

Strategy for querying a temporal object.

Queries are a key tool for extracting information from temporal objects.
They exist to externalize the process of querying, permitting different
approaches, as per the strategy design pattern.
Examples might be a query that checks if the date is the day before February 29th
in a leap year, or calculates the number of days to your next birthday.

The TemporalField interface provides another mechanism for querying
temporal objects. That interface is limited to returning a long.
By contrast, queries can return any type.

There are two equivalent ways of using a TemporalQuery.
The first is to invoke the method on this interface directly.
The second is to use TemporalAccessor.query(TemporalQuery):


  // these two lines are equivalent, but the second approach is recommended
  temporal = thisQuery.queryFrom(temporal);
  temporal = temporal.query(thisQuery);
It is recommended to use the second approach, query(TemporalQuery),
as it is a lot clearer to read in code.

The most common implementations are method references, such as
LocalDate::from and ZoneId::from.
Additional common queries are provided as static methods in TemporalQueries.

A unit of date-time, such as Days or Hours.

Measurement of time is built on units, such as years, months, days, hours, minutes and seconds.
Implementations of this interface represent those units.

An instance of this interface represents the unit itself, rather than an amount of the unit.
See Period for a class that represents an amount in terms of the common units.

The most commonly used units are defined in ChronoUnit.
Further units are supplied in IsoFields.
Units can also be written by application code by implementing this interface.

The unit works using double dispatch. Client code calls methods on a date-time like
LocalDateTime which check if the unit is a ChronoUnit.
If it is, then the date-time must handle it.
Otherwise, the method call is re-dispatched to the matching method in this interface.

UnsupportedTemporalTypeException indicates that a ChronoField or ChronoUnit is
not supported for a Temporal class.

The range of valid values for a date-time field.

All TemporalField instances have a valid range of values.
For example, the ISO day-of-month runs from 1 to somewhere between 28 and 31.
This class captures that valid range.

It is important to be aware of the limitations of this class.
Only the minimum and maximum values are provided.
It is possible for there to be invalid values within the outer range.
For example, a weird field may have valid values of 1, 2, 4, 6, 7, thus
have a range of '1 - 7', despite that fact that values 3 and 5 are invalid.

Instances of this class are not tied to a specific field.

Localized definitions of the day-of-week, week-of-month and week-of-year fields.

A standard week is seven days long, but cultures have different definitions for some
other aspects of a week. This class represents the definition of the week, for the
purpose of providing TemporalField instances.

WeekFields provides five fields,
dayOfWeek(), weekOfMonth(), weekOfYear(),
weekOfWeekBasedYear(), and weekBasedYear()
that provide access to the values from any java.time.temporal.temporal object.

The computations for day-of-week, week-of-month, and week-of-year are based
on the  proleptic-year,
month-of-year,
day-of-month, and
ISO day-of-week which are based on the
epoch-day and the chronology.
The values may not be aligned with the year-of-Era
depending on the Chronology.
A week is defined by:

The first day-of-week.
For example, the ISO-8601 standard considers Monday to be the first day-of-week.
The minimal number of days in the first week.
For example, the ISO-8601 standard counts the first week as needing at least 4 days.

Together these two values allow a year or month to be divided into weeks.

Week of Month
One field is used: week-of-month.
The calculation ensures that weeks never overlap a month boundary.
The month is divided into periods where each period starts on the defined first day-of-week.
The earliest period is referred to as week 0 if it has less than the minimal number of days
and week 1 if it has at least the minimal number of days.


Examples of WeekFields
DateDay-of-week
 First day: MondayMinimal days: 4First day: MondayMinimal days: 5
2008-12-31Wednesday
 Week 5 of December 2008Week 5 of December 2008
2009-01-01Thursday
 Week 1 of January 2009Week 0 of January 2009
2009-01-04Sunday
 Week 1 of January 2009Week 0 of January 2009
2009-01-05Monday
 Week 2 of January 2009Week 1 of January 2009


Week of Year
One field is used: week-of-year.
The calculation ensures that weeks never overlap a year boundary.
The year is divided into periods where each period starts on the defined first day-of-week.
The earliest period is referred to as week 0 if it has less than the minimal number of days
and week 1 if it has at least the minimal number of days.

Week Based Year
Two fields are used for week-based-year, one for the
week-of-week-based-year and one for
week-based-year.  In a week-based-year, each week
belongs to only a single year.  Week 1 of a year is the first week that
starts on the first day-of-week and has at least the minimum number of days.
The first and last weeks of a year may contain days from the
previous calendar year or next calendar year respectively.


Examples of WeekFields for week-based-year
DateDay-of-week
 First day: MondayMinimal days: 4First day: MondayMinimal days: 5
2008-12-31Wednesday
 Week 1 of 2009Week 53 of 2008
2009-01-01Thursday
 Week 1 of 2009Week 53 of 2008
2009-01-04Sunday
 Week 1 of 2009Week 53 of 2008
2009-01-05Monday
 Week 2 of 2009Week 1 of 2009

A year in the ISO-8601 calendar system, such as 2007.

Year is an immutable date-time object that represents a year.
Any field that can be derived from a year can be obtained.

Note that years in the ISO chronology only align with years in the
Gregorian-Julian system for modern years. Parts of Russia did not switch to the
modern Gregorian/ISO rules until 1920.
As such, historical years must be treated with caution.

This class does not store or represent a month, day, time or time-zone.
For example, the value "2007" can be stored in a Year.

Years represented by this class follow the ISO-8601 standard and use
the proleptic numbering system. Year 1 is preceded by year 0, then by year -1.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which today's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
However, any application that makes use of historical dates, and requires them
to be accurate will find the ISO-8601 approach unsuitable.


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

A year-month in the ISO-8601 calendar system, such as 2007-12.

YearMonth is an immutable date-time object that represents the combination
of a year and month. Any field that can be derived from a year and month, such as
quarter-of-year, can be obtained.

This class does not store or represent a day, time or time-zone.
For example, the value "October 2007" can be stored in a YearMonth.

The ISO-8601 calendar system is the modern civil calendar system used today
in most of the world. It is equivalent to the proleptic Gregorian calendar
system, in which today's rules for leap years are applied for all time.
For most applications written today, the ISO-8601 rules are entirely suitable.
However, any application that makes use of historical dates, and requires them
to be accurate will find the ISO-8601 approach unsuitable.


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

A transition between two offsets caused by a discontinuity in the local time-line.

A transition between two offsets is normally the result of a daylight savings cutover.
The discontinuity is normally a gap in spring and an overlap in autumn.
ZoneOffsetTransition models the transition between the two offsets.

Gaps occur where there are local date-times that simply do not exist.
An example would be when the offset changes from +03:00 to +04:00.
This might be described as 'the clocks will move forward one hour tonight at 1am'.

Overlaps occur where there are local date-times that exist twice.
An example would be when the offset changes from +04:00 to +03:00.
This might be described as 'the clocks will move back one hour tonight at 2am'.

A rule expressing how to create a transition.

This class allows rules for identifying future transitions to be expressed.
A rule might be written in many forms:

the 16th March
the Sunday on or after the 16th March
the Sunday on or before the 16th March
the last Sunday in February

These different rule types can be expressed and queried.

The rules defining how the zone offset varies for a single time-zone.

The rules model all the historic and future transitions for a time-zone.
ZoneOffsetTransition is used for known transitions, typically historic.
ZoneOffsetTransitionRule is used for future transitions that are based
on the result of an algorithm.

The rules are loaded via ZoneRulesProvider using a ZoneId.
The same rules may be shared internally between multiple zone IDs.

Serializing an instance of ZoneRules will store the entire set of rules.
It does not store the zone ID as it is not part of the state of this object.

A rule implementation may or may not store full information about historic
and future transitions, and the information stored is only as accurate as
that supplied to the implementation by the rules provider.
Applications should treat the data provided as representing the best information
available to the implementation of this rule.

Thrown to indicate a problem with time-zone configuration.

This exception is used to indicate a problems with the configured
time-zone rules.

Provider of time-zone rules to the system.

This class manages the configuration of time-zone rules.
The static methods provide the public API that can be used to manage the providers.
The abstract methods provide the SPI that allows rules to be provided.

ZoneRulesProvider may be installed in an instance of the Java Platform as
extension classes, that is, jar files placed into any of the usual extension
directories. Installed providers are loaded using the service-provider loading
facility defined by the ServiceLoader class. A ZoneRulesProvider
identifies itself with a provider configuration file named
java.time.zone.ZoneRulesProvider in the resource directory
META-INF/services. The file should contain a line that specifies the
fully qualified concrete zonerules-provider class name.
Providers may also be made available by adding them to the class path or by
registering themselves via registerProvider(java.time.zone.ZoneRulesProvider) method.

The Java virtual machine has a default provider that provides zone rules
for the time-zones defined by IANA Time Zone Database (TZDB). If the system
property java.time.zone.DefaultZoneRulesProvider is defined then
it is taken to be the fully-qualified name of a concrete ZoneRulesProvider
class to be loaded as the default provider, using the system class loader.
If this system property is not defined, a system-default provider will be
loaded to serve as the default provider.

Rules are looked up primarily by zone ID, as used by ZoneId.
Only zone region IDs may be used, zone offset IDs are not used here.

Time-zone rules are political, thus the data can change at any time.
Each provider will provide the latest rules for each zone ID, but they
may also provide the history of how the rules changed.

A date-time with a time-zone in the ISO-8601 calendar system,
such as 2007-12-03T10:15:30+01:00 Europe/Paris.

ZonedDateTime is an immutable representation of a date-time with a time-zone.
This class stores all date and time fields, to a precision of nanoseconds,
and a time-zone, with a zone offset used to handle ambiguous local date-times.
For example, the value
"2nd October 2007 at 13:45.30.123456789 02:00 in the Europe/Paris time-zone"
can be stored in a ZonedDateTime.

This class handles conversion from the local time-line of LocalDateTime
to the instant time-line of Instant.
The difference between the two time-lines is the offset from UTC/Greenwich,
represented by a ZoneOffset.

Converting between the two time-lines involves calculating the offset using the
rules accessed from the ZoneId.
Obtaining the offset for an instant is simple, as there is exactly one valid
offset for each instant. By contrast, obtaining the offset for a local date-time
is not straightforward. There are three cases:

Normal, with one valid offset. For the vast majority of the year, the normal
 case applies, where there is a single valid offset for the local date-time.
Gap, with zero valid offsets. This is when clocks jump forward typically
 due to the spring daylight savings change from "winter" to "summer".
 In a gap there are local date-time values with no valid offset.
Overlap, with two valid offsets. This is when clocks are set back typically
 due to the autumn daylight savings change from "summer" to "winter".
 In an overlap there are local date-time values with two valid offsets.


Any method that converts directly or implicitly from a local date-time to an
instant by obtaining the offset has the potential to be complicated.

For Gaps, the general strategy is that if the local date-time falls in the
middle of a Gap, then the resulting zoned date-time will have a local date-time
shifted forwards by the length of the Gap, resulting in a date-time in the later
offset, typically "summer" time.

For Overlaps, the general strategy is that if the local date-time falls in the
middle of an Overlap, then the previous offset will be retained. If there is no
previous offset, or the previous offset is invalid, then the earlier offset is
used, typically "summer" time.. Two additional methods,
withEarlierOffsetAtOverlap() and withLaterOffsetAtOverlap(),
help manage the case of an overlap.

In terms of design, this class should be viewed primarily as the combination
of a LocalDateTime and a ZoneId. The ZoneOffset is
a vital, but secondary, piece of information, used to ensure that the class
represents an instant, especially during a daylight savings overlap.


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

A time-zone ID, such as Europe/Paris.

A ZoneId is used to identify the rules used to convert between
an Instant and a LocalDateTime.
There are two distinct types of ID:

Fixed offsets - a fully resolved offset from UTC/Greenwich, that uses
 the same offset for all local date-times
Geographical regions - an area where a specific set of rules for finding
 the offset from UTC/Greenwich apply

Most fixed offsets are represented by ZoneOffset.
Calling normalized() on any ZoneId will ensure that a
fixed offset ID will be represented as a ZoneOffset.

The actual rules, describing when and how the offset changes, are defined by ZoneRules.
This class is simply an ID used to obtain the underlying rules.
This approach is taken because rules are defined by governments and change
frequently, whereas the ID is stable.

The distinction has other effects. Serializing the ZoneId will only send
the ID, whereas serializing the rules sends the entire data set.
Similarly, a comparison of two IDs only examines the ID, whereas
a comparison of two rules examines the entire data set.

Time-zone IDs
The ID is unique within the system.
There are three types of ID.

The simplest type of ID is that from ZoneOffset.
This consists of 'Z' and IDs starting with '+' or '-'.

The next type of ID are offset-style IDs with some form of prefix,
such as 'GMT+2' or 'UTC+01:00'.
The recognised prefixes are 'UTC', 'GMT' and 'UT'.
The offset is the suffix and will be normalized during creation.
These IDs can be normalized to a ZoneOffset using normalized().

The third type of ID are region-based IDs. A region-based ID must be of
two or more characters, and not start with 'UTC', 'GMT', 'UT' '+' or '-'.
Region-based IDs are defined by configuration, see ZoneRulesProvider.
The configuration focuses on providing the lookup from the ID to the
underlying ZoneRules.

Time-zone rules are defined by governments and change frequently.
There are a number of organizations, known here as groups, that monitor
time-zone changes and collate them.
The default group is the IANA Time Zone Database (TZDB).
Other organizations include IATA (the airline industry body) and Microsoft.

Each group defines its own format for the region ID it provides.
The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'.
TZDB IDs take precedence over other groups.

It is strongly recommended that the group name is included in all IDs supplied by
groups other than TZDB to avoid conflicts. For example, IATA airline time-zone
region IDs are typically the same as the three letter airport code.
However, the airport of Utrecht has the code 'UTC', which is obviously a conflict.
The recommended format for region IDs from groups other than TZDB is 'group~region'.
Thus if IATA data were defined, Utrecht airport would be 'IATA~UTC'.

Serialization
This class can be serialized and stores the string zone ID in the external form.
The ZoneOffset subclass uses a dedicated format that only stores the
offset from UTC/Greenwich.

A ZoneId can be deserialized in a Java Runtime where the ID is unknown.
For example, if a server-side Java Runtime has been updated with a new zone ID, but
the client-side Java Runtime has not been updated. In this case, the ZoneId
object will exist, and can be queried using getId, equals,
hashCode, toString, getDisplayName and normalized.
However, any call to getRules will fail with ZoneRulesException.
This approach is designed to allow a ZonedDateTime to be loaded and
queried, but not modified, on a Java Runtime with incomplete time-zone information.


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

A time-zone offset from Greenwich/UTC, such as +02:00.

A time-zone offset is the amount of time that a time-zone differs from Greenwich/UTC.
This is usually a fixed number of hours and minutes.

Different parts of the world have different time-zone offsets.
The rules for how offsets vary by place and time of year are captured in the
ZoneId class.

For example, Paris is one hour ahead of Greenwich/UTC in winter and two hours
ahead in summer. The ZoneId instance for Paris will reference two
ZoneOffset instances - a +01:00 instance for winter,
and a +02:00 instance for summer.

In 2008, time-zone offsets around the world extended from -12:00 to 14:00.
To prevent any problems with that range being extended, yet still provide
validation, the range of offsets is restricted to -18:00 to 18:00 inclusive.

This class is designed for use with the ISO calendar system.
The fields of hours, minutes and seconds make assumptions that are valid for the
standard ISO definitions of those fields. This class may be used with other
calendar systems providing the definition of the time fields matches those
of the ISO calendar system.

Instances of ZoneOffset must be compared using equals(java.lang.Object).
Implementations may choose to cache certain common offsets, however
applications must not rely on such caching.


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