Type Members

1.  final class ChronoField extends Enum[ChronoField] with TemporalField
2.  final class ChronoUnit extends Enum[ChronoUnit] with TemporalUnit
3.  trait Temporal extends TemporalAccessor

   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.

   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.

   Specification for implementors

   This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended. All implementations must be Comparable.

4.  trait TemporalAccessor extends AnyRef

   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.

   Specification for implementors

   This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.

5.  trait TemporalAdjuster extends AnyRef

   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.

   Specification for implementors

   This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.

6.  trait TemporalAmount extends AnyRef

   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.

   Specification for implementors

   This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.

7.  trait TemporalField extends AnyRef

   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.

   Specification for implementors

   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.

8.  trait TemporalQuery[+R] extends AnyRef

   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.

   Specification for implementors

   This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended.

9.  trait TemporalUnit extends AnyRef

   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.

   Specification for implementors

   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.

10.  class UnsupportedTemporalTypeException extends DateTimeException

    An exception that indicates a type is unsupported.

    An exception that indicates a type is unsupported.

    Specification for implementors

    This class is intended for use in a single thread.

    Constructs a new date-time exception with the specified message and cause.

11.  final class ValueRange extends Serializable

    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.

    Specification for implementors

    This class is immutable and thread-safe.

12.  final class WeekFields extends Serializable

    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:

    • 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

    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

    === 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. This class is immutable and thread-safe.

    Annotations

    @SerialVersionUID()

    Exceptions thrown

    IllegalArgumentException if the minimal days value is invalid