1. Overview
The Java LocalDateTime API represents and manipulates a combination of date and time. ZonedDateTime is an immutable object that holds a date-time value to a precision of nanoseconds, a time zone value based on the ISO 8601 calendar system, and a ZoneOffSet to handle ambiguous local date-times.
In this tutorial, we’ll see how to convert from LocalDateTime to ZonedDateTime and vice-versa.
2. Convert LocalDateTime to ZonedDateTime
Let’s begin by converting an instance of LocalDateTime to ZonedDateTime.
2.1. Using the atZone() Method
The atZone() method from the LocalDateTime instance performs the conversion to ZonedDateTime and maintains the same date-time values:
LocalDateTime localDateTime = LocalDateTime.of(2022, 1, 1, 0, 30, 22);
ZonedDateTime zonedDateTime = localDateTime.atZone(ZoneId.of("Canada/Atlantic"));
assertEquals(localDateTime.getYear(), zonedDateTime.getYear());
assertEquals(localDateTime.getMonth(), zonedDateTime.getMonth());
assertEquals(localDateTime.getDayOfMonth(), zonedDateTime.getDayOfMonth());
assertEquals(localDateTime.getHour(), zonedDateTime.getHour());
assertEquals(localDateTime.getMinute(), zonedDateTime.getMinute());
assertEquals(localDateTime.getSecond(), zonedDateTime.getSecond());
The atZone() method receives the ZoneId value that specifies the time zone based on the ISO 8601 calendar system.
Invoking the withZoneSameInstant() method converts to the actual date-time values using the ZoneOffSet time difference:
LocalDateTime localDateTime = LocalDateTime.of(2022, 1, 1, 0, 30, 22);
ZonedDateTime zonedDateTime = localDateTime.atZone(ZoneId.of("Africa/Lagos")).withZoneSameInstant(ZoneId.of("Canada/Atlantic"));
assertEquals("2021-12-31T19:30:22-04:00[Canada/Atlantic]", zonedDateTime.toString());
assertEquals("-04:00", zonedDateTime.getOffset().toString());
We can obtain available ZoneIds by invoking the static ZoneId.getAvailableZoneIds() method. This method returns a set of all available region-based IDs, as Strings, that we can select from to create a ZoneId object.
Furthermore, the conversion with atZone() also comes with a ZoneOffSet value that provides the time difference (-04:00 in the example above) between the ZonedDateTime object and the UTC (GMT).
2.2. Using the ZonedDateTime.of() Method
The ZonedDateTime class also provides a static of() method to create a ZonedDateTime object. The method accepts instances of LocalDateTime and ZoneId as arguments and returns a ZonedDateTime object:
LocalDateTime localDateTime = LocalDateTime.of(2022, 11, 5, 7, 30, 22);
ZonedDateTime zonedDateTime = ZonedDateTime.of(localDateTime, ZoneId.of("Africa/Accra")).withZoneSameInstant(ZoneId.of("Africa/Lagos"));
assertEquals("2022-11-05T08:30:22+01:00[Africa/Lagos]", zonedDateTime.toString());
assertEquals(localDateTime.getYear(), zonedDateTime.getYear());
In this case, too, as we saw earlier, we can obtain the actual date-time values of the given zone by invoking the withZoneSameInstant() method.
2.3. Using the ZonedDateTime.ofInstant() Method
We can also use a ZoneOffSet object in combination with LocalDateTime to create a ZonedDateTime object.
The static ofInstant() method accepts LocalDateTime, ZoneOffSet, and ZoneId objects as arguments:
LocalDateTime localDateTime = LocalDateTime.of(2022, 1, 5, 17, 30, 22);
ZoneId zoneId = ZoneId.of("Africa/Lagos");
ZoneOffset zoneOffset = zoneId.getRules().getOffset(localDateTime);
ZonedDateTime zonedDateTime = ZonedDateTime.ofInstant(localDateTime, zoneOffset, zoneId);
assertEquals("2022-01-05T17:30:22+01:00[Africa/Lagos]", zonedDateTime.toString());
The ZonedDateTime object is created from the Instant object implicitly formed by combining the LocalDateTime and ZoneOffSet objects.
2.4. Using the ZonedDateTime.ofLocal() Method
The static ofLocal() method creates a ZonedDateTime from the LocalDateTime object with the preferred ZoneOffSet object passed as an argument:
LocalDateTime localDateTime = LocalDateTime.of(2022, 8 , 25, 8, 35, 22);
ZoneId zoneId = ZoneId.of("Africa/Lagos");
ZoneOffset zoneOffset = zoneId.getRules().getOffset(localDateTime);
ZonedDateTime zonedDateTime = ZonedDateTime.ofLocal(localDateTime, zoneId, zoneOffset);
assertEquals("2022-08-25T08:35:22+01:00[Africa/Lagos]", zonedDateTime.toString());
Usually, only one valid offset exists for a local date-time. When a time overlap occurs, then there would be two valid offsets.
If the preferred ZoneOffset passed as an argument is one of the valid offsets, then it is used. Otherwise, the conversion maintains the previous valid offset.
2.5. Using the ZonedDateTime.ofStrict() Method
Similarly, the static ofStrict() method returns a ZonedDateTime object by strictly validating the combination of LocalDateTime, ZoneOffSet, and ZoneID arguments:
LocalDateTime localDateTime = LocalDateTime.of(2022, 12, 25, 6, 18, 2);
ZoneId zoneId = ZoneId.of("Asia/Tokyo");
ZoneOffset zoneOffset = zoneId.getRules().getOffset(localDateTime);
ZonedDateTime zonedDateTime = ZonedDateTime.ofStrict(localDateTime, zoneOffset, zoneId);
assertEquals("2002-12-25T06:18:02+09:00[Asia/Tokyo]", zonedDateTime.toString());
The method throws a DateTimeException if we provide an invalid combination of arguments:
zoneId = ZoneId.of("Asia/Tokyo");
zoneOffset = ZoneOffset.UTC;
assertThrows(DateTimeException.class, () -> ZonedDateTime.ofStrict(localDateTime, zoneOffset, zoneId));
The above example shows that an exception is thrown when we attempt to create a ZonedDateTime object using a combination of ZoneId from Asia/Tokyo and a ZoneOffSet value representing the default UTC (GMT + 0).
3. Convert ZonedDateTime to LocalDateTime
A ZonedDateTime object maintains three distinct objects: a LocalDateTime, a ZoneId, and a ZoneOffset.
We can convert an instance of ZonedDateTime to LocalDateTime using the toLocalDateTime() method:
ZonedDateTime zonedDateTime = ZonedDateTime.of(2011, 2, 12, 6, 14, 1, 58086000, ZoneId.of("Asia/Tokyo"));
LocalDateTime localDateTime = zonedDateTime.toLocalDateTime();
assertEquals("2011-02-12T06:14:01.058086+09:00[Asia/Tokyo]", zonedDateTime.toString());
This method retrieves the LocalDateTime object stored as part of the ZonedDateTime properties.
4. Conclusion
In this article, we learned how to convert an instance of LocalDateTime to ZonedDateTime and vice versa.
As always, the source code for the examples is available over on GitHub.
