The ZonedDateTime Class – Date and Time
By Gigi Rosen / July 24, 2024 / No Comments / Compact Number Parsing, Conditional Formatting, Creating Resource Bundles, Formatting and Parsing Messages, Oracle Certifications, The ZonedDateTime Class
The ZonedDateTime Class
The ZonedDateTime class represents a date-time with time zone information, and an instance of the class is referred to as a zoned date-time (Table 17.1, p. 1025). The date and time fields are stored with nanosecond precision. The time zone information is represented by a time zone with a zone offset from UTC/Greenwich. In essence, a zoned date-time represents an instant on a specific timeline determined by its zone ID and its zone offset from UTC/Greenwich. This timeline is referred to as the local timeline, whereas the timeline at UTC/Greenwich is referred to as the instant timeline.
A majority of the methods in the ZonedDateTime class should be familiar from the temporal classes discussed earlier in this chapter (p. 1027). Both Table 17.2, p. 1026, and Table 17.3, p. 1026, showing the common method name prefixes and common methods, apply to the ZonedDateTime class as well. The LocalDateTime class is the closest equivalent of the ZonedDateTime class.
Issues relating to daylight savings are covered later in this section (p. 1082). In particular, the methods of(), with(), minus(), and plus() take into consideration daylight savings.
The methods get(), with(), plus(), minus(), and until() throw an UnsupportedTemporalTypeException when an unsupported field is accessed, and a DateTimeException when the operation cannot be performed for any other reason.
Objects of the ZonedDateTime class are also immutable and thread-safe. The class also overrides the equals() and the hashCode() methods of the Object class, but in contrast to the LocalDateTime class, its objects are not comparable.
With that overview, we turn our attention to dealing with zoned date-times as represented by the ZonedDateTime class.
Creating Zoned Date-Time
Analogous to the other temporal classes, the current zoned date-time can be obtained from the system clock in either the default time zone or a specific time zone by calling the now() method of the ZonedDateTime class. The zoned date-times created at (1a), (2a), and (3a) represent the same date-time locally in the default time zone Europe/Oslo, at UTC/Greenwich (UTC), and in the US/Eastern time zone, respectively.
The text representation of the zoned date-times from (1a), (2a), and (3a) is shown below at (1b), (2b), and (3b), respectively. The text representation of a zoned date-time returned by the toString() method shows the date and the time separated by the letter T, followed by the zone offset and the time zone.
ZonedDateTime defaultZDT = ZonedDateTime.now(); // (1a)
ZonedDateTime utcZDT = ZonedDateTime.now(ZoneId.of(“UTC”)); // (2a)
ZonedDateTime edtZDT = ZonedDateTime.now(ZoneId.of(“US/Eastern”)); // (3a)
System.out.println(“Default Zone Date-time: ” + defaultZDT);
System.out.println(“UTC Date-time: ” + utcZDT);
System.out.println(“EDT Zone Date-time: ” + edtZDT);
Output from the print statements:
Default Zone Date-time: 2021-07-11T11:35:20.008+02:00[Europe/Oslo] // (1b)
UTC Date-time: 2021-07-11T09:35:20.023Z[UTC] // (2b)
EDT Zone Date-time: 2021-07-11T05:35:20.023-04:00[US/Eastern] // (3b)
The local time in the Europe/Oslo time zone has the zone offset +02:00—meaning it is 2 hours ahead of UTC/Greenwich, as it is east of Greenwich. The date-time at UTC/Greenwich (UTC) has no zone offset, just the letter Z instead of an offset. The local time in the US/Eastern time zone has the zone offset -04:00—meaning it is 4 hours behind UTC/Greenwich, as it is west of Greenwich. On this particular date, the time difference between the Europe/Oslo time zone and the US/Eastern time zone is 6 hours, where daylight saving time is in effect in both time zones (p. 1082).
One convenient way to create a zoned date-time is to assemble it from its constituent parts. We will use the following declarations to create zoned date-times.
LocalTime concertTime = LocalTime.of(00, 10); // 00:10
LocalDate concertDate = LocalDate.of(1973, Month.JANUARY, 14); // 1973-01-14
LocalDateTime concertDT = LocalDateTime.of(concertDate,
concertTime); // 1973-01-14T00:10
ZoneId hwZID = ZoneId.of(“US/Hawaii”); // US/Hawaii
Instant instantZ = Instant.ofEpochSecond(95854200); // 1973-01-14T10:10:00Z
The code below creates three zoned date-times from constituent parts. The arguments in the method call comprise the parts of a zoned date-time in each case. We note that the zone offset of the US/Hawaii time zone is -10:00—that is, 10 hours behind UTC/Greenwich. Note how the ofInstant() method converts the time in the instant to the correct local time in the specified time zone.
ZonedDateTime concertZDT0 = ZonedDateTime.of(concertDate, concertTime, hwZID);
ZonedDateTime concertZDT1 = ZonedDateTime.of(concertDT, hwZID);
ZonedDateTime concertZDT2 = ZonedDateTime.ofInstant(instantZ, hwZID);
// 1973-01-14T00:10-10:00[US/Hawaii]
boolean areEqual = concertZDT0.equals(concertZDT1)
&& concertZDT0.equals(concertZDT2); // true
The LocalDateTime and the Instant classes also provide the atZone() method that combines a date-time or an instant, respectively, with a time zone to create a zoned date-time. The two zoned date-times created below are equal to the three created earlier.
ZonedDateTime concertZDT3 = concertDT.atZone(hwZID);
ZonedDateTime concertZDT4 = instantZ.atZone(hwZID);
// 1973-01-14T00:10-10:00[US/Hawaii]
We can also use the parse() method to create a zoned date-time from a text string that is compatible with the ISO format (p. 1129).
ZonedDateTime concertZDT5
= ZonedDateTime.parse(“1973-01-14T00:10-10:00[US/Hawaii]”);
static ZonedDateTime now()
static ZonedDateTime now(ZoneId zone)
Return a ZonedDateTime containing the current date-time from the system clock in the default time zone or in the specified time zone, respectively.
static ZonedDateTime of(int year, int month, int dayOfMonth, int hour,
int minute, int second, int nanoOfSecond, ZoneId zone)
static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone)
static ZonedDateTime of(LocalDateTime localDateTime, ZoneId zone)
static ZonedDateTime ofInstant(Instant instant, ZoneId zone)
Return a ZonedDateTime formed from the specified arguments. Note the zone argument that is required. The methods throw a DateTimeException when the operation cannot be performed for some reason.
Note that these methods take into consideration any adjustments because of daylight savings (p. 1082).
static ZonedDateTime parse(CharSequence text)
Returns a ZonedDateTime by parsing the text string according to DateTimeFormatter.ISO_ZONED_DATE_TIME (p. 1129)—for example, “2021-07-03T16:15:30+01:00 [Europe/Oslo]”.
String toString()
Returns a string comprising the text representation of the constituent parts: the LocalDateTime, typically followed by the zone offset and the time zone—for example, 2021-07-11T05:35:20.023-04:00[US/Eastern].