Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / Java

ZonedDateTime: stesso istante o stessa ora locale?

In Java 21, crea una data e ora con fuso orario, seleziona esplicitamente ciascuna occorrenza di un orario ripetuto e scegli se conservare l’istante o l’ora locale.

Versione: Java SE 21

Sintassi

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 combina una data e un’ora locali con un identificatore di fuso (ZoneId) e uno scostamento da UTC (ZoneOffset). Un Instant è un punto sulla linea temporale. La data e l’ora locali sono ciò che mostrano il calendario e l’orologio: in un dato fuso possono indicare due istanti distinti.

ZonedDateTime.of è un metodo factory statico con tre overload: accetta un LocalDateTime, un LocalDate e un LocalTime, oppure sette campi numerici, sempre insieme a un ZoneId. Se c’è un solo scostamento valido, lo usa. In una sovrapposizione, cioè un intervallo locale ripetuto, sceglie lo scostamento della prima occorrenza. In un intervallo saltato, fa avanzare data e ora locali della durata dell’intervallo e usa lo scostamento successivo alla transizione. Campi di data o ora non validi nell’overload numerico causano una DateTimeException.

ZonedDateTime.ofLocal(localDateTime, zone, preferredOffset) è un metodo factory statico. In una sovrapposizione usa lo scostamento preferito solo se è uno dei due validi. Con null o con un valore che non corrisponde, sceglie la prima occorrenza. Con un solo scostamento valido o in un intervallo saltato, si comporta come of. Una preferenza non è una convalida: se l’app deve rifiutare gli intervalli saltati o esigere una scelta esplicita nelle sovrapposizioni, esamina zone.getRules().getValidOffsets(localDateTime), che restituisce 0, 1 o 2 scostamenti.

ZonedDateTime.withZoneSameInstant(zone) mostra lo stesso evento in un altro fuso: toInstant() restituisce un valore uguale anche se cambiano la data o l’ora locali. Non occorre risolvere salti o sovrapposizioni locali; un risultato fuori dall’intervallo di date supportato causa una DateTimeException. ZonedDateTime.withZoneSameLocal(zone) interpreta la stessa data e ora come locali al fuso di destinazione, quindi l’istante può cambiare. Segue le regole di ofLocal, con lo scostamento corrente come preferenza. In un intervallo saltato non conserva la data e l’ora locali originali. Nessuno dei due metodi modifica l’oggetto di partenza.

Esempi

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));
    }
}

Risultato

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

Con le regole di `Europe/Paris` usate nell’esempio, `02:30` si presenta due volte: `+02:00` dà `00:30Z` e `+01:00` dà `01:30Z`. `of` sceglie la prima occorrenza; le due chiamate a `ofLocal` selezionano entrambi gli scostamenti in modo esplicito. Passando dalla prima occorrenza a UTC si ottiene `00:30Z` se si conserva l’istante, o `02:30Z` se si conserva l’ora indicata dall’orologio. I risultati per un fuso regionale dipendono dalle regole disponibili nell’ambiente di esecuzione.

Lezioni correlate

  • Java · Lezione 60 · Avanzato · Versione: 2

Fonti