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

CKTIS / Java

ZoneId.of e ZoneId.getRules: regras dos fusos horários

Consulta os desvios em relação a UTC em Varsóvia e Nova Iorque no mesmo instante de 2025 e vê por que razão um desvio fixo não substitui um fuso horário regional.

Versão: Java SE 21

Sintaxe

java.time.ZoneId
  public static ZoneId of(String zoneId)
  public static ZoneId of(String zoneId, java.util.Map<String, String> aliasMap)
  public abstract java.time.zone.ZoneRules getRules()

O método de fábrica estático ZoneId.of(String), de java.time, valida um identificador e devolve um ZoneId. Europe/Warsaw e America/New_York identificam fusos horários regionais; +01:00 dá um ZoneOffset, um desvio fixo em relação a UTC. Dois fusos podem ter o mesmo desvio num instante sem seguir as mesmas regras.

A sobrecarga ZoneId.of(String, Map<String, String>) permite fornecer o teu próprio mapa de nomes alternativos para identificadores. Prefere identificadores regionais a abreviaturas ambíguas. Um formato inválido provoca uma DateTimeException; um identificador regional bem formado, mas desconhecido, provoca uma ZoneRulesException, um subtipo de DateTimeException.

O método de instância ZoneId.getRules() devolve um objeto imutável java.time.zone.ZoneRules. getOffset(Instant) devolve o único desvio em vigor nesse instante. Para um LocalDateTime, usa getValidOffsets: devolve zero desvios no intervalo saltado ao adiantar o relógio, um fora de uma transição e normalmente dois no intervalo repetido ao atrasá-lo. Em teoria, pode haver mais de dois desvios válidos se o relógio for atrasado duas vezes num curto espaço de tempo. Num intervalo saltado ou repetido, getOffset(LocalDateTime) devolve o desvio anterior à transição, que no intervalo saltado não é válido para a hora local indicada.

As regras regionais vêm de um ZoneRulesProvider; a fonte de dados predefinida é a TZDB da IANA. Os resultados históricos dependem dos dados do ambiente de execução. Um fornecedor que suporte atualizações dinâmicas pode devolver regras diferentes numa chamada posterior a getRules(). Se as regras de um identificador desserializado não estiverem disponíveis, getRules() lança uma ZoneRulesException.

Exemplos

import java.time.Instant;
import java.time.ZoneId;
import java.time.zone.ZoneRules;

public class Main {
    public static void main(String[] args) {
        ZoneRules warsaw = ZoneId.of("Europe/Warsaw").getRules();
        ZoneRules newYork = ZoneId.of("America/New_York").getRules();
        ZoneRules fixed = ZoneId.of("+01:00").getRules();

        System.out.println("UTC instant | Europe/Warsaw | America/New_York | fixed +01:00");
        for (String timestamp : new String[] {
                "2025-03-01T12:00:00Z", "2025-03-15T12:00:00Z", "2025-04-01T12:00:00Z"
        }) {
            Instant instant = Instant.parse(timestamp);
            System.out.println(instant + " | " + warsaw.getOffset(instant)
                    + " | " + newYork.getOffset(instant) + " | " + fixed.getOffset(instant));
        }
    }
}

Resultado

UTC instant | Europe/Warsaw | America/New_York | fixed +01:00
2025-03-01T12:00:00Z | +01:00 | -05:00 | +01:00
2025-03-15T12:00:00Z | +01:00 | -04:00 | +01:00
2025-04-01T12:00:00Z | +02:00 | -04:00 | +01:00

Cada linha compara o mesmo instante UTC. A 15 de março de 2025, em Nova Iorque já vigora a hora de verão, mas em Varsóvia ainda não. A 1 de abril, Varsóvia também já mudou de desvio; o desvio fixo `+01:00` mantém-se.

Lições relacionadas

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

Fontes