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-only access to a temporal object, such as a date, time, offset or some combination of these.
Strategy for adjusting a temporal object.
Framework-level interface defining an amount of time, such as "6 hours", "8 days" or "2 years and 3 months".
A field of date-time, such as month-of-year or hour-of-minute.
Strategy for querying a temporal object.
A unit of date-time, such as Days or Hours.
An exception that indicates a type is unsupported.
The range of valid values for a date-time field.
Localized definitions of the day-of-week, week-of-month and week-of-year fields.
A standard set of fields.
A standard set of date periods units.
Fields and units specific to the ISO-8601 calendar system, including quarter-of-year and week-based-year.
A set of date fields that provide access to Julian Days.
Common implementations of TemporalAdjuster
.
Common implementations of TemporalQuery
.
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.Temporal
provides 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
LocalDate
calledgetDayOfMonth()
. 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.TemporalAdjuster
and 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.WeekFields
class 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
.