CKTIS / Java
ZonedDateTime: Same instant or same wall-clock time?
In Java 21, create a zoned date-time, explicitly select either occurrence of a repeated local time, and change zones without confusing the instant with the clock reading.
Version: Java SE 21
Syntax
java.time.ZonedDateTime — Java SE 21
public static ZonedDateTime of(LocalDateTime localDateTime, ZoneId zone)
public static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone)
public static ZonedDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone)
public static ZonedDateTime ofLocal(LocalDateTime localDateTime, ZoneId zone, ZoneOffset preferredOffset)
public ZonedDateTime withZoneSameInstant(ZoneId zone)
public ZonedDateTime withZoneSameLocal(ZoneId zone)java.time.ZonedDateTime combines a local date and time with a zone ID (ZoneId) and a UTC offset (ZoneOffset). An instant (Instant) is a point on the timeline. A local date and time is what the calendar and clock show; in a given zone, that reading can refer to two different instants.
ZonedDateTime.of is a static factory with three overloads: pass a LocalDateTime, a LocalDate and LocalTime, or seven numeric fields, plus a ZoneId in each case. It uses the sole valid offset when there is one. In an overlap (a repeated local interval), it picks the offset for the first occurrence. In a gap (a skipped local interval), it adds the length of the gap to the local date-time and uses the post-transition offset. Invalid date or time fields in the numeric overload cause DateTimeException.
ZonedDateTime.ofLocal(localDateTime, zone, preferredOffset) is a static factory. In an overlap it uses the preferred offset only if it is one of the two valid offsets; null or a nonmatching offset falls back to the first occurrence. With one valid offset or in a gap, it behaves like of. A preference is not validation: if your app must reject gaps or require an explicit choice in overlaps, inspect zone.getRules().getValidOffsets(localDateTime), which returns 0, 1, or 2 offsets.
ZonedDateTime.withZoneSameInstant(zone) shows the same event in another zone: toInstant() still compares equal, even if the local date or time changes. There is no local gap or overlap to resolve; a result outside the supported date range causes DateTimeException. ZonedDateTime.withZoneSameLocal(zone) treats the same date and clock reading as local to the target zone, so the instant can change. It follows the ofLocal rules, using the current offset as the preference. In a gap it cannot keep the original local date-time. Neither method mutates the original value.
Examples
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
public class ZonedDateTimeTransform {
public static void main(String[] args) {
ZoneId paris = ZoneId.of("Europe/Paris");
LocalDateTime wallTime = LocalDateTime.of(2024, 10, 27, 2, 30);
ZonedDateTime defaultChoice = ZonedDateTime.of(wallTime, paris);
ZonedDateTime earlier = ZonedDateTime.ofLocal(wallTime, paris, ZoneOffset.ofHours(2));
ZonedDateTime later = ZonedDateTime.ofLocal(wallTime, paris, ZoneOffset.ofHours(1));
System.out.println("of: " + defaultChoice);
System.out.println("ofLocal +02:00: " + earlier + " -> " + earlier.toInstant());
System.out.println("ofLocal +01:00: " + later + " -> " + later.toInstant());
System.out.println("same instant: " + earlier.withZoneSameInstant(ZoneOffset.UTC));
System.out.println("same local: " + earlier.withZoneSameLocal(ZoneOffset.UTC));
}
}Result
of: 2024-10-27T02:30+02:00[Europe/Paris] ofLocal +02:00: 2024-10-27T02:30+02:00[Europe/Paris] -> 2024-10-27T00:30:00Z ofLocal +01:00: 2024-10-27T02:30+01:00[Europe/Paris] -> 2024-10-27T01:30:00Z same instant: 2024-10-27T00:30Z same local: 2024-10-27T02:30Z
Under the `Europe/Paris` rules used in the example, `02:30` occurs twice: `+02:00` gives `00:30Z`, and `+01:00` gives `01:30Z`. `of` picks the first occurrence; the two `ofLocal` calls explicitly select both offsets. Converting the first occurrence to UTC gives `00:30Z` when preserving the instant and `02:30Z` when preserving the clock reading. Results for a region zone depend on the rules available to the runtime.
Related lessons
- Java · Lesson 60 · Advanced · Version: 2