17.1 Date and Time API Overview

The java.time package provides the main support for dealing with dates and times. It contains the main classes that represent date and time values, including those that represent an amount of time.

• LocalDate: This class represents a date in terms of date fields (year, month, day). A date has no time fields or a time zone. (This class is not to be confused with the java.util.Date legacy class.)
• LocalTime: This class represents time in a 24-hour day in terms of time fields (hour, minute, second, nanosecond). A time has no date fields or a time zone.
• LocalDateTime: This class represents the concept of date and time combined, in terms of both date and time fields. A date-time has no time zone.
• ZonedDateTime: This class represents the concept of a date-time with a time zone— that is, a zoned date-time.
• Instant: This class represents a measurement of time as a point on a timeline starting from a specific origin (called the epoch). An instant is represented with nanosecond precision and can be a negative value.
• Period: This class represents an amount or quantity of time in terms of number of days, months, and years, which can be negative. A period is a date-based amount of time. It has no notion of a clock time, a date, or a time zone.
• Duration: This class represents an amount or quantity of time in terms of number of seconds and nanoseconds, which can be negative. A duration is a time-based amount of time. As with instants, durations have no notion of a clock time, a date, or a time zone.

We will use the term temporal objects to mean objects of classes that represent temporal concepts.

The temporal classes implement immutable and thread-safe temporal objects. The state of an immutable object cannot be changed. Any method that is supposed to modify such an object returns a modified copy of the temporal object. It is a common mistake to ignore the object returned, thinking that the current object has been modified. Thread-safety guarantees that the state of such an object is not compromised by concurrent access.

Table 17.1 summarizes the fields in selected classes from the Date and Time API. The table shows the relative size of the objects of these classes in terms of their fields; for example, a LocalTime has only time fields, whereas a ZonedDateTime has time-, date-, and zone-based fields. The three asterisks *** indicate that this information can be derived by methods provided by the class, even though these fields do not exist in an object of the Duration class.

Table 17.1 Fields in Selected Classes in the Date and Time API

Classes	Year	Month	Day	Hours	Minutes	Seconds/Nanos	Zone offset	Zone ID
LocalTime (p. 1027)				+	+	+
LocalDate (p. 1027)	+	+	+
LocalDateTime (p. 1027)	+	+	+	+	+	+
ZonedDate-Time (p. 1072)	+	+	+	+	+	+	+	+
Instant (p. 1049)						+
Period (p. 1057)	+	+	+
Duration (p. 1064)			***	***	***	+

The information in Table 17.1 is crucial to understanding how the objects of these classes can be used. A common mistake is to access, format, or parse a temporal object that does not have the required temporal fields. For example, a LocalTime object has only time fields, so trying to format it with a formatter for date fields will result in a java.time.DateTimeException. Many methods will also throw an exception if an invalid or an out-of-range argument is passed in the method call. It is important to keep in mind which temporal fields constitute the state of a temporal object.

Table 17.2 provides an overview of the method naming conventions used in the temporal classes LocalTime, LocalDate, LocalDateTime, ZonedDateTime, and Instant. This method naming convention makes it easy to use the API, as it ensures method naming is standardized across all temporal classes. Depending on the method, the suffix XXX in a method name can be a specific field (e.g., designate the Year field in the getYear method name), a specific unit (e.g., designate the unit Days for number of days in the plusDays method name), or a class name (e.g., designate the class type in the toLocalDate method name).

Table 17.2 Selected Method Name Prefixes in the Temporal Classes

Prefix (parameters not shown)	Usage
atXXX()	Create a new temporal object by combining this temporal object with another temporal object. Not provided by the ZonedDateTime class.
of() ofXXX()	Static factory methods for constructing temporal objects from constituent temporal fields.
get() getXXX()	Access specific fields in this temporal object.
isXXX()	Check specific properties of this temporal object.
minus() minusXXX()	Return a copy of this temporal object after subtracting an amount of time.
plus() plusXXX()	Return a copy of this temporal object after adding an amount of time.
toXXX()	Convert this temporal object to another type.
with() withXXX()	Create a copy of this temporal object with one field modified.

Apart from the methods shown in Table 17.2, the selected methods shown in Table 17.3 are common to the temporal classes LocalTime, LocalDate, LocalDateTime, ZonedDateTime, and Instant.

Table 17.3 Selected Common Methods in the Temporal Classes

Method (parameters not shown)	Usage
now()	Static method that obtains the current time from the system or specified clock in the default or specified time zone.
from()	Static method to obtain an instance of this temporal class from another temporal.
until()	Calculate the amount of time from this temporal object to another temporal object.
toString()	Create a text representation of this temporal object.
equals()	Compare two temporal objects for equality.
hashCode()	Returns a hash code for this temporal object.
compareTo()	Compare two temporal objects. (The class ZonedDateTime does not implement the Comparable<E> interface.)
parse()	Static method to obtain a temporal instance from a specified text string (§18.6, p. 1127).
format()	Create a text representation of this temporal object using a specified formatter (§18.6, p. 1127). (Instant class does not provide this method.)

Subsequent sections in this chapter provide ample examples of how to create, combine, convert, access, and compare temporal objects, including the use of temporal arithmetic and dealing with time zones and daylight savings. For formatting and parsing temporal objects, see §18.6, p. 1127.