The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
The java.time.temporal package provides a collection of interfaces, classes, and enums that support date and time code and, in particular, date and time calculations.
These interfaces are intended to be used at the lowest level. Typical application code should declare variables and parameters in terms of the concrete type, such as LocalDate or ZonedDateTime, and not in terms of the Temporal interface. This is exactly the same as declaring a variable of type String, and not of type CharSequence.
The Temporal interface provides a framework for accessing temporal-based objects, and is implemented by the temporal-based classes, such as Instant, LocalDateTime, and ZonedDateTime. This interface provides methods to add or subtract units of time, making time-based arithmetic easy and consistent across the various date and time classes. The TemporalAccessor interface provides a read-only version of the Temporal interface.
Both Temporal and TemporalAccessor objects are defined in terms of fields, as specified in the TemporalField interface. The ChronoField enum is a concrete implementation of the TemporalField interface and provides a rich set of defined constants, such as DAY_OF_WEEK, MINUTE_OF_HOUR, and MONTH_OF_YEAR.
The units for these fields are specified by the TemporalUnit interface. The ChronoUnit enum implements the TemporalUnit interface. The field ChronoField.DAY_OF_WEEK is a combination of ChronoUnit.DAYS and ChronoUnit.WEEKS. The ChronoField and ChronoUnit enums are discussed in the following sections.
The arithmetic-based methods in the Temporal interface require parameters defined in terms of TemporalAmount values. The Period and Duration classes (discussed in Period and Duration) implement the TemporalAmount interface.
The ChronoField enum, which implements the TemporalField interface, provides a rich set of constants for accessing date and time values. A few examples are CLOCK_HOUR_OF_DAY, NANO_OF_DAY, and DAY_OF_YEAR. This enum can be used to express conceptual aspects of time, such as the third week of the year, the 11th hour of the day, or the first Monday of the month. When you encounter a Temporal of unknown type, you can use the TemporalAccessor.isSupported(TemporalField) method to determine if the Temporal supports a particular field. The following line of code returns false, indicating that LocalDate does not support ChronoField.CLOCK_HOUR_OF_DAY:
boolean isSupported = LocalDate.now().isSupported(ChronoField.CLOCK_HOUR_OF_DAY);
Additional fields, specific to the ISO-8601 calendar system, are defined in the IsoFields class. The following examples show how to obtain the value of a field using both ChronoField and IsoFields:
time.get(ChronoField.MILLI_OF_SECOND) int qoy = date.get(IsoFields.QUARTER_OF_YEAR);
Two other classes define additional fields that may be useful, WeekFields and JulianFields.
The ChronoUnit enum implements the TemporalUnit interface, and provides a set of standard units based on date and time, from milliseconds to millennia. Note that not all ChronoUnit objects are supported by all classes. For example, the Instant class does not support ChronoUnit.MONTHS or ChronoUnit.YEARS. Classes in the Date-Time API contain the isSupported(TemporalUnit) method that can be used to verify whether a class supports a particular time unit. The following call to isSupported returns false, confirming that the Instant class does not support ChronoUnit.DAYS.
Instant instant = Instant.now(); boolean isSupported = instant.isSupported(ChronoUnit.DAYS);