temporal
Framework-level interface defining read-write access to a temporal object, such as a date, time, offset or some combination of these.
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 fields or 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 chronology and the time-zone.
These can be accessed via queries using
the static methods defined on TemporalQueries.
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.
A class should implement this interface if it meets three criteria:
TemporalAccessorFour 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.This interface places no restrictions on the mutability of implementations,
however immutability is strongly recommended.
All implementations must be Comparable.
Framework-level interface defining read-only access to a temporal object, such as a date, time, offset or some combination of these.
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 fields or 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 chronology and the time-zone.
These can be accessed via queries using
the static methods defined on TemporalQueries.
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.
This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.
Strategy for adjusting a temporal object.
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.See TemporalAdjusters for a standard set of adjusters, including finding the
last day of the month.
Adjusters may also be defined by applications.
This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.
Framework-level interface defining an amount of time, such as "6 hours", "8 days" or "2 years and 3 months".
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.
This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.
A field of date-time, such as month-of-year or hour-of-minute.
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.
This interface must be implemented with care to ensure other classes operate correctly.
All implementations that can be instantiated must be final, immutable and thread-safe.
Implementations should be Serializable where possible.
An enum is as effective implementation choice.
Strategy for querying a temporal object.
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.
Further implementations are on TemporalQueries.
Queries may also be defined by applications.
This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.
A unit of date-time, such as Days or Hours.
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.
This interface must be implemented with care to ensure other classes operate correctly. All implementations that can be instantiated must be final, immutable and thread-safe. It is recommended to use an enum where possible.
An exception that indicates a type is unsupported.
An exception that indicates a type is unsupported.
This class is intended for use in a single thread.
Constructs a new date-time exception with the specified message and cause.
The range of valid values for a date-time field.
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.
This class is immutable and thread-safe.
Localized definitions of the day-of-week, week-of-month and week-of-year fields.
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 three fields,
#dayOfWeek(), #weekOfMonth(), and #weekOfYear()
that provide access to the values from any 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:
Together these two values allow a year or month to be divided into weeks.
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.
| Date | Day-of-week | First day: Monday Minimal days: 4 | First day: Monday Minimal days: 5 |
|---|---|---|---|
| 2008-12-31 | Wednesday | Week 5 of December 2008 | Week 5 of December 2008 |
| 2009-01-01 | Thursday | Week 1 of January 2009 | Week 0 of January 2009 |
| 2009-01-04 | Sunday | Week 1 of January 2009 | Week 0 of January 2009 |
| 2009-01-05 | Monday | Week 2 of January 2009 | Week 1 of January 2009 |
IllegalArgumentException if the minimal days value is invalid
A standard set of fields.
A standard set of fields.
This set of fields provide field-based access to manipulate a date, time or date-time.
The standard set of fields can be extended by implementing TemporalField.
These fields are intended to be applicable in multiple calendar systems. For example, most non-ISO calendar systems define dates as a year, month and day, just with slightly different rules. The documentation of each field explains how it operates.
This is a final, immutable and thread-safe enum.
A standard set of date periods units.
A standard set of date periods units.
This set of units provide unit-based access to manipulate a date, time or date-time.
The standard set of units can be extended by implementing TemporalUnit.
These units are intended to be applicable in multiple calendar systems. For example, most non-ISO calendar systems define units of years, months and days, just with slightly different rules. The documentation of each unit explains how it operates.
This is a final, immutable and thread-safe enum.
Fields and units specific to the ISO-8601 calendar system, including quarter-of-year and week-based-year.
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.
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 92QUARTER_OF_YEAR - the week within the week-based-yearYEAR - the standard ISO yearThe 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-yearWEEK_BASED_YEAR - the week-based-yearThe 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.
There are 52 weeks in most week-based years, however on occasion there are 53 weeks.
For example:
| Date | Day-of-week | Field values |
|---|---|---|
| 2008-12-28 | Sunday | Week 52 of week-based-year 2008 |
| 2008-12-29 | Monday | Week 1 of week-based-year 2009 |
| 2008-12-31 | Wednesday | Week 1 of week-based-year 2009 |
| 2009-01-01 | Thursday | Week 1 of week-based-year 2009 |
| 2009-01-04 | Sunday | Week 1 of week-based-year 2009 |
| 2009-01-05 | Monday | Week 2 of week-based-year 2009 |
This class is immutable and thread-safe.
A set of date fields that provide access to Julian Days.
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.
This is an immutable and thread-safe class.
Common implementations of TemporalAdjuster.
Common implementations of TemporalAdjuster.
This class provides common implementations of TemporalAdjuster.
They are especially useful to document the intent of business logic and
often link well to requirements.
For example, these two pieces of code do the same thing, but the second
one is clearer (assuming that there is a static import of this class):
// direct manipulation date.withDayOfMonth(1).plusMonths(1).minusDays(1); // use of an adjuster from this class date.with(lastDayOfMonth());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 dateTime = adjuster.adjustInto(dateTime); dateTime = dateTime.with(adjuster);It is recommended to use the second approach,
with(TemporalAdjuster),
as it is a lot clearer to read in code.This is a thread-safe utility class. All returned adjusters are immutable and thread-safe.
Common implementations of TemporalQuery.
Common implementations of TemporalQuery.
This class provides common implementations of TemporalQuery.
These queries are primarily used as optimizations, allowing the internals
of other objects to be extracted effectively. Note that application code
can also use the from(TemporalAccessor) method on most temporal
objects as a method reference matching the query interface, such as
LocalDate::from and ZoneId::from.
There are two equivalent ways of using a TemporalQuery.
The first is to invoke the method on the interface directly.
The second is to use TemporalAccessor#query(TemporalQuery):
// these two lines are equivalent, but the second approach is recommended dateTime = query.queryFrom(dateTime); dateTime = dateTime.query(query);It is recommended to use the second approach,
query(TemporalQuery),
as it is a lot clearer to read in code.This is a thread-safe utility class. All returned adjusters are immutable and thread-safe.
Access to date and time using fields and units.
This package expands on the base package to provide additional functionality for more powerful use cases. Support is included for:
Fields and Units
Dates and times are expressed in terms of fields and units. A unit is used to measure an amount of time, such as years, days or minutes. All units implement
org.threeten.bp.temporal.TemporalUnit. The set of well known units is defined inorg.threeten.bp.temporal.ChronoUnit, for example,org.threeten.bp.temporal.ChronoUnit#DAYS. The unit interface is designed to allow applications to add their own units.A field is used to express part of a larger date-time, such as year, month-of-year or second-of-minute. All fields implement
org.threeten.bp.temporal.TemporalField. The set of well known fields are defined inorg.threeten.bp.temporal.ChronoField, for example,org.threeten.bp.temporal.ChronoField#HOUR_OF_DAY. An additional fields are defined byorg.threeten.bp.temporal.JulianFields. The field interface is designed to allow applications to add their own fields.This package provides tools that allow the units and fields of date and time to be accessed in a general way most suited for frameworks.
org.threeten.bp.temporal.Temporalprovides the abstraction for date time types that support fields. Its methods support getting the value of a field, creating a new date time with the value of a field modified, and extracting another date time type, typically used to extract the offset or time-zone.One use of fields in application code is to retrieve fields for which there is no convenience method. For example, getting the day-of-month is common enough that there is a method on
LocalDatecalledgetDayOfMonth(). However for more unusual fields it is necessary to use the field. For example,date.get(ChronoField.ALIGNED_WEEK_OF_MONTH). The fields also provide access to the range of valid values.Adjustment
A key part of the date-time problem space is adjusting a date to a new, related value, such as the "last day of the month", or "next Wednesday". These are modeled as functions that adjust a base date-time. The functions implement
org.threeten.bp.temporal.TemporalAdjusterand operate onorg.threeten.bp.temporal.Temporal. A set of common functions are provided inorg.threeten.bp.temporal.TemporalAdjusters. For example, to find the first occurrence of a day-of-week after a given date, useorg.threeten.bp.temporal.TemporalAdjusters#next(DayOfWeek), such asdate.with(next(MONDAY)).Weeks
Different locales have different definitions of the week. For example, in Europe the week typically starts on a Monday, while in the US it starts on a Sunday. The
org.threeten.bp.temporal.WeekFieldsclass models this distinction.The ISO calendar system defines an additional week-based division of years. This defines a year based on whole Monday to Monday weeks. This is modeled in
org.threeten.bp.temporal.IsoFields.