Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

ZonedDateTime: o mesmo instante ou a mesma hora local?

Cria uma data e hora com fuso horário em Java 21, escolhe explicitamente cada ocorrência de uma hora repetida e muda de fuso mantendo o instante ou a hora local.

Versão: Java SE 21

Sintaxe

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 uma data e hora locais com um identificador de fuso horário (ZoneId) e um desvio em relação a UTC (ZoneOffset). Um Instant é um ponto na linha do tempo. A data e hora locais são as que aparecem no calendário e no relógio; num dado fuso, podem indicar dois instantes diferentes.

ZonedDateTime.of é um método de fábrica estático com três sobrecargas: aceita um LocalDateTime, um LocalDate e um LocalTime, ou sete campos numéricos, sempre com um ZoneId. Se houver um único desvio válido, usa-o. Numa sobreposição, ou seja, num intervalo local repetido, escolhe o desvio da primeira ocorrência. Numa lacuna, ou seja, num intervalo local que o relógio salta, avança a data e hora locais pela duração da lacuna e usa o desvio após a transição. Campos de data ou hora inválidos na sobrecarga numérica provocam uma DateTimeException.

ZonedDateTime.ofLocal(localDateTime, zone, preferredOffset) é um método de fábrica estático. Numa sobreposição, só usa o desvio preferido se for um dos dois válidos. Com null ou um desvio que não corresponda a nenhum deles, escolhe a primeira ocorrência. Se houver um único desvio válido ou se houver uma lacuna, comporta-se como of. Uma preferência não serve de validação: se a aplicação tiver de rejeitar lacunas ou exigir uma escolha explícita nas sobreposições, consulta zone.getRules().getValidOffsets(localDateTime), que devolve 0, 1 ou 2 desvios.

ZonedDateTime.withZoneSameInstant(zone) apresenta o mesmo acontecimento noutro fuso: o valor de toInstant() mantém-se igual, mesmo que a data ou a hora local mude. Não é necessário resolver lacunas ou sobreposições locais; um resultado fora do intervalo de datas suportado provoca uma DateTimeException. ZonedDateTime.withZoneSameLocal(zone) interpreta a mesma data e hora como locais ao fuso de destino, pelo que o instante pode mudar. Segue as regras de ofLocal e usa o desvio atual como preferência. Numa lacuna, não consegue manter a data e hora locais originais. Nenhum dos métodos altera o objeto original.

Exemplos

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

Resultado

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

Pelas regras de `Europe/Paris` usadas no exemplo, `02:30` ocorre duas vezes: com `+02:00` corresponde a `00:30Z` e com `+01:00` a `01:30Z`. `of` escolhe a primeira ocorrência; as duas chamadas a `ofLocal` selecionam explicitamente ambos os desvios. Ao passar a primeira ocorrência para UTC, obtém-se `00:30Z` se for mantido o instante, ou `02:30Z` se for mantida a hora do relógio. Os resultados para um fuso regional dependem das regras disponíveis no ambiente de execução.

Lições relacionadas

  • Java · Lição 60 · Avançado · Versão: 2

Fontes