Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / Java

ZonedDateTime : même instant ou même heure locale ?

Avec Java 21, créez une date-heure avec fuseau, choisissez explicitement chacune des deux occurrences d’une heure répétée et distinguez les deux façons de changer de fuseau.

Version : Java SE 21

Syntaxe

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 associe une date et une heure locales à un identifiant de fuseau (ZoneId) et à un décalage par rapport à UTC (ZoneOffset). Un Instant est un point sur la ligne du temps. La date et l’heure locales sont celles qu’affichent le calendrier et l’horloge ; dans un fuseau donné, elles peuvent désigner deux instants différents.

ZonedDateTime.of est une fabrique statique à trois surcharges : elle accepte un LocalDateTime, un LocalDate et un LocalTime, ou sept champs numériques, toujours accompagnés d’un ZoneId. Elle utilise l’unique décalage valide s’il n’y en a qu’un. Lors d’un chevauchement, c’est-à-dire d’un intervalle local répété, elle prend le décalage de la première occurrence. Dans un intervalle sauté, elle avance la date-heure locale de la durée de cet intervalle et applique le décalage qui suit la transition. Des champs de date ou d’heure invalides dans la surcharge numérique provoquent une DateTimeException.

ZonedDateTime.ofLocal(localDateTime, zone, preferredOffset) est une fabrique statique. Dans un chevauchement, elle applique le décalage préféré uniquement s’il fait partie des deux décalages valides. Si la préférence vaut null ou ne correspond à aucun des deux, elle choisit la première occurrence. Hors chevauchement, elle se comporte comme of. Une préférence ne valide pas la saisie : pour refuser les intervalles sautés ou imposer un choix explicite en cas de chevauchement, examinez zone.getRules().getValidOffsets(localDateTime), qui renvoie 0, 1 ou 2 décalages.

ZonedDateTime.withZoneSameInstant(zone) affiche le même événement dans un autre fuseau : toInstant() donne une valeur égale, même si la date ou l’heure locale change. Il n’y a ni intervalle sauté ni chevauchement local à résoudre ; un résultat hors de la plage de dates prise en charge provoque une DateTimeException. ZonedDateTime.withZoneSameLocal(zone) interprète la même date et la même heure comme locales au fuseau cible : l’instant peut donc changer. La méthode suit les règles de ofLocal, avec le décalage actuel comme préférence. Dans un intervalle sauté, elle ne peut pas conserver la date-heure locale initiale. Aucune de ces méthodes ne modifie l’objet d’origine.

Exemples

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

Résultat

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

Selon les règles de `Europe/Paris` utilisées dans l’exemple, `02:30` se produit deux fois : `+02:00` donne `00:30Z` et `+01:00` donne `01:30Z`. `of` choisit la première occurrence ; les deux appels à `ofLocal` choisissent explicitement les deux décalages. En passant de la première occurrence à UTC, on obtient `00:30Z` si l’instant est conservé et `02:30Z` si l’heure affichée est conservée. Les résultats pour un fuseau régional dépendent des règles dont dispose l’environnement d’exécution.

Leçons associées

  • Java · Leçon 60 · Avancé · Version : 2

Sources