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