Knowledge baseExam Center
ENEnglish
Choose language13

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

Sources