Класс ZoneId

java.lang.Object

java.time.ZoneId

Все реализуемые интерфейсы:: Serializable

Непосредственные известные подклассы:: ZoneOffset

public abstract sealed class ZoneId extends Object implements Serializable permits ZoneOffset (not exhaustive)

Идентификатор часового пояса, например, Europe/Paris.

Идентификатор ZoneId используется для определения правил преобразования между Instant и LocalDateTime. Существует два основных типа идентификаторов:

Фиксированные смещения — полностью определенное смещение от UTC/Гринвича, которое используется для всех локальных дат и времён
Географические регионы — область, для которой определён набор правил определения смещения от UTC/Гринвича

Большинство фиксированных смещений представляются с помощью ZoneOffset. Вызов normalized() для любого ZoneId гарантирует, что идентификатор фиксированного смещения будет представлен как ZoneOffset.

Фактические правила, описывающие, когда и как меняется смещение, определены в ZoneRules. Этот класс — просто идентификатор, используемый для получения базовых правил. Такой подход используется, поскольку правила определяются правительствами и часто меняются, а идентификатор остаётся стабильным.

Это различие имеет другие последствия. Сериализация ZoneId передаёт только идентификатор, в то время как сериализация правил отправляет весь набор данных. Аналогично, сравнение двух идентификаторов проверяет только идентификатор, в то время как сравнение двух правил проверяет весь набор данных.

Идентификаторы часовых поясов

Идентификатор уникален в системе. Существует три типа идентификаторов.

Самый простой тип идентификатора — из ZoneOffset. Он включает 'Z' и идентификаторы, начинающиеся с '+' или '-'.

Следующий тип — идентификаторы стиля смещения с каким-либо префиксом, например, 'GMT+2' или 'UTC+01:00'. Признанные префиксы — 'UTC', 'GMT' и 'UT'. Смещение является суффиксом и будет нормализовано при создании. Эти идентификаторы можно нормализовать до ZoneOffset с помощью normalized().

Третий тип — идентификаторы на основе региона. Идентификатор на основе региона должен состоять из двух или более символов и не начинаться с 'UTC', 'GMT', 'UT', '+' или '-'. Идентификаторы на основе региона определяются конфигурацией, см. ZoneRulesProvider. Конфигурация сосредоточена на предоставлении поиска по идентификатору базового ZoneRules.

Правила часовых поясов определяются правительствами и часто меняются. Существует ряд организаций, известных здесь как группы, которые отслеживают изменения часовых поясов и собирают их. По умолчанию используется база данных часовых поясов IANA (TZDB). Другие организации включают IATA (организация авиационной отрасли) и Microsoft.

Каждая группа определяет свой собственный формат идентификатора региона, который она предоставляет. Группа TZDB определяет идентификаторы, такие как 'Europe/London' или 'America/New_York'. Идентификаторы TZDB имеют приоритет перед другими группами.

Настоятельно рекомендуется включать имя группы во всех идентификаторах, предоставленных группами, отличными от TZDB, чтобы избежать конфликтов. Например, идентификаторы регионов часовых поясов IATA обычно совпадают с трёхбуквенным кодом аэропорта. Однако аэропорт Утрехта имеет код 'UTC', что очевидно является конфликтом. Рекомендуемый формат для идентификаторов регионов от групп, отличных от TZDB, — 'group~region'. Таким образом, если были определены данные IATA, аэропорт Утрехта будет 'IATA~UTC'.

Сериализация

Этот класс может быть сериализован и хранит строковый идентификатор часового пояса во внешней форме. Подкласс ZoneOffset использует специальный формат, который хранит только смещение от UTC/Гринвича.

ZoneId может быть десериализован в среде выполнения Java, где идентификатор неизвестен. Например, если серверная среда выполнения Java была обновлена с новым идентификатором часового пояса, а клиентская среда выполнения Java — нет. В этом случае объект ZoneId будет существовать и может быть запрошен с помощью getId, equals, hashCode, toString, getDisplayName и normalized. Однако любой вызов getRules завершится ошибкой ZoneRulesException. Этот подход разработан для того, чтобы ZonedDateTime мог загружаться и запрашиваться, но не изменяться в среде выполнения Java с неполной информацией о часовых поясах.

Это класс с базовыми значениями; программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать экземпляры для синхронизации, иначе может произойти непредсказуемое поведение. Например, в будущих версиях синхронизация может быть нарушена. Для сравнений следует использовать метод equals.

Требования к реализации:

Этот абстрактный запечатанный класс допускает две реализации, обе из которых неизменяемы и потокобезопасны. Одна реализация моделирует идентификаторы на основе регионов, другая — ZoneOffset, моделирующая идентификаторы на основе смещений. Это различие видно в сериализации.

Диаграмма иерархии запечатанного класса:

С:

1.8

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final Map<String,String>`	`SHORT_IDS`	Карта переопределений часовых поясов для использования коротких названий часовых поясов.

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`equals(Object obj)`	Проверяет, равен ли этот идентификатор часового пояса другому идентификатору часового пояса.
`static ZoneId`	`from(TemporalAccessor temporal)`	Получает экземпляр `ZoneId` из временного объекта.
`static Set<String>`	`getAvailableZoneIds()`	Получает набор доступных идентификаторов часовых поясов.
`String`	`getDisplayName(TextStyle style, Locale locale)`	Получает текстовое представление часового пояса, например, 'British Time' или '+02:00'.
`abstract String`	`getId()`	Получает уникальный идентификатор часового пояса.
`abstract ZoneRules`	`getRules()`	Получает правила часового пояса для этого идентификатора, позволяющие выполнять вычисления.
`int`	`hashCode()`	Хеш-код для этого идентификатора часового пояса.
`ZoneId`	`normalized()`	Нормализует идентификатор часового пояса, возвращая `ZoneOffset`, если это возможно.
`static ZoneId`	`of(String zoneId)`	Получает экземпляр `ZoneId` по идентификатору, гарантируя, что идентификатор является допустимым и доступным для использования.
`static ZoneId`	`of(String zoneId, Map<String,String> aliasMap)`	Получает экземпляр `ZoneId` по его идентификатору, используя карту псевдонимов для дополнения стандартных идентификаторов часовых поясов.
`static ZoneId`	`ofOffset(String prefix, ZoneOffset offset)`	Получает экземпляр `ZoneId`, оборачивающий смещение.
`static ZoneId`	`systemDefault()`	Получает системный часовой пояс по умолчанию.
`String`	`toString()`	Выводит этот часовой пояс как `String`, используя идентификатор.

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Краткое описание полей

SHORT_IDS

public static final Map<String,String> SHORT_IDS

Карта переопределений зон для использования коротких имен часовых поясов.

Использование коротких идентификаторов зон устарело в java.util.TimeZone. Эта карта позволяет продолжать использовать идентификаторы через метод фабрики of(String, Map).

Эта карта содержит сопоставление идентификаторов, соответствующее TZDB 2024b и более поздним версиям, где 'EST', 'MST' и 'HST' сопоставляются с идентификаторами, которые не включают летнее время с 1970 года. Это сопоставление может измениться в обновленных выпусках в поддержку новых версий TZDB.

Сопоставление выглядит следующим образом:

ACT - Australia/Darwin
AET - Australia/Sydney
AGT - America/Argentina/Buenos_Aires
ART - Africa/Cairo
AST - America/Anchorage
BET - America/Sao_Paulo
BST - Asia/Dhaka
CAT - Africa/Harare
CNT - America/St_Johns
CST - America/Chicago
CTT - Asia/Shanghai
EAT - Africa/Addis_Ababa
ECT - Europe/Paris
EST - America/Panama
HST - Pacific/Honolulu
IET - America/Indiana/Indianapolis
IST - Asia/Kolkata
JST - Asia/Tokyo
MIT - Pacific/Apia
MST - America/Phoenix
NET - Asia/Yerevan
NST - Pacific/Auckland
PLT - Asia/Karachi
PNT - America/Phoenix
PRT - America/Puerto_Rico
PST - America/Los_Angeles
SST - Pacific/Guadalcanal
VST - Asia/Ho_Chi_Minh

Карта является неизменяемой.

Краткое описание методов

systemDefault

public static ZoneId systemDefault()

Получает часовой пояс по умолчанию системы.

Этот запрос к TimeZone.getDefault() находит часовой пояс по умолчанию и преобразует его в ZoneId. Если часовой пояс системы по умолчанию изменяется, то результат этого метода также изменится.

Возвращает:: идентификатор зоны, не null
Исключения:: DateTimeException - если преобразованный идентификатор зоны имеет неверный формат; ZoneRulesException - если преобразованный идентификатор региона зоны не найден

getAvailableZoneIds

public static Set<String> getAvailableZoneIds()

Получает набор доступных идентификаторов зон.

Этот набор включает строковую форму всех доступных идентификаторов на основе региона. Идентификаторы зон на основе смещения не включены в возвращаемый набор. Идентификатор может быть передан в of(String) для создания ZoneId.

Набор идентификаторов зон может увеличиваться со временем, хотя в типичном приложении набор идентификаторов фиксирован. Каждый вызов этого метода потокобезопасен.

Возвращает:: изменяемая копия набора идентификаторов зон, не null

of

public static ZoneId of(String zoneId, Map<String,String> aliasMap)

Получает экземпляр ZoneId используя его ID, используя карту псевдонимов для дополнения стандартных идентификаторов зон.

Многие пользователи часовых поясов используют короткие сокращения, такие как PST для 'Pacific Standard Time' и PDT для 'Pacific Daylight Time'. Эти сокращения не уникальны и поэтому не могут использоваться в качестве идентификаторов. Этот метод позволяет настроить карту строки в часовой пояс и повторно использовать её в приложении.

Параметры:: zoneId - идентификатор часового пояса, не null; aliasMap - карта псевдонимов идентификаторов зон (обычно сокращений) для реальных идентификаторов зон, не null
Возвращает:: идентификатор зоны, не null
Исключения:: DateTimeException - если идентификатор зоны имеет неверный формат; ZoneRulesException - если идентификатор зоны является идентификатором региона, который не может быть найден

of

public static ZoneId of(String zoneId)

Получает экземпляр ZoneId из идентификатора, гарантируя, что идентификатор действителен и доступен для использования.

Этот метод разбирает идентификатор, создавая ZoneId или ZoneOffset. ZoneOffset возвращается, если идентификатор равен 'Z' или начинается с '+' или '-'. Результатом всегда будет действительный идентификатор, для которого можно получить ZoneRules.

Разбор соответствует идентификатору зоны шаг за шагом следующим образом.

Если идентификатор зоны равен 'Z', результатом является ZoneOffset.UTC.
Если идентификатор зоны состоит из одной буквы, идентификатор зоны неверен и возникает исключение DateTimeException.
Если идентификатор зоны начинается с '+' или '-', идентификатор разбирается как ZoneOffset используя ZoneOffset.of(String).
Если идентификатор зоны равен 'GMT', 'UTC' или 'UT', то результатом является ZoneId с тем же идентификатором и правилами, эквивалентными ZoneOffset.UTC.
Если идентификатор зоны начинается с 'UTC+', 'UTC-', 'GMT+', 'GMT-', 'UT+' или 'UT-', то идентификатор является идентификатором на основе смещения с префиксом. Идентификатор делится на две части: двух- или трехбуквенный префикс и суффикс, начинающийся со знака. Суффикс разбирается как ZoneOffset. Результатом будет ZoneId с указанным префиксом UTC/GMT/UT и нормализованным идентификатором смещения согласно ZoneOffset.getId(). Правила возвращаемого ZoneId будут эквивалентны разобранному ZoneOffset.
Все остальные идентификаторы разбираются как идентификаторы зон на основе региона. Идентификаторы регионов должны соответствовать регулярному выражению [A-Za-z][A-Za-z0-9~/._+-]+, иначе возникает исключение DateTimeException. Если идентификатор зоны не находится в настроенном наборе идентификаторов, возникает исключение ZoneRulesException. Подробный формат идентификатора региона зависит от группы, предоставляющей данные. Набор данных по умолчанию предоставляется базой данных часовых поясов IANA (TZDB). Он имеет идентификаторы регионов в формате '{area}/{city}', такие как 'Europe/Paris' или 'America/New_York'. Это совместимо с большинством идентификаторов из TimeZone.

Параметры:: zoneId - идентификатор часового пояса, не null
Возвращает:: идентификатор зоны, не null
Исключения:: DateTimeException - если идентификатор зоны имеет неверный формат; ZoneRulesException - если идентификатор зоны является идентификатором региона, который не может быть найден

ofOffset

public static ZoneId ofOffset(String prefix, ZoneOffset offset)

Получает экземпляр ZoneId, оборачивающий смещение.

Если префикс равен "GMT", "UTC" или "UT", возвращается ZoneId с префиксом и ненулевым смещением. Если префикс пуст "", возвращается ZoneOffset.

Параметры:: prefix - идентификатор часового пояса, не null; offset - смещение, не null
Возвращает:: идентификатор зоны, не null
Исключения:: IllegalArgumentException - если префикс не является одним из "GMT", "UTC" или "UT", или ""

from

public static ZoneId from(TemporalAccessor temporal)

Получает экземпляр ZoneId из временного объекта.

Это получает зону на основе указанного временного объекта. TemporalAccessor представляет собой произвольный набор информации о дате и времени, который эта фабрика преобразует в экземпляр ZoneId.

TemporalAccessor представляет собой некоторую форму информации о дате и времени. Эта фабрика преобразует произвольный временной объект в экземпляр ZoneId.

Преобразование попытается получить зону таким образом, чтобы отдавать предпочтение зонам на основе региона перед зонами на основе смещения, используя TemporalQueries.zone().

Этот метод соответствует сигнатуре функционального интерфейса TemporalQuery, что позволяет использовать его в качестве запроса через ссылку на метод, ZoneId::from.

Параметры:: temporal - временной объект для преобразования, не null
Возвращает:: идентификатор зоны, не null
Исключения:: DateTimeException - если невозможно преобразовать в ZoneId

getId

public abstract String getId()

Получает уникальный идентификатор часового пояса.

Этот идентификатор однозначно определяет этот объект. Формат идентификатора на основе смещения определяется ZoneOffset.getId().

Возвращает:: уникальный идентификатор часового пояса, не null

getDisplayName

public String getDisplayName(TextStyle style, Locale locale)

Получает текстовое представление зоны, например, 'British Time' или '+02:00'.

Это возвращает текстовое имя, используемое для идентификации идентификатора часового пояса, подходящее для представления пользователю. Параметры управляют стилем возвращаемого текста и языком.

Если текстовое сопоставление не найдено, возвращается full ID.

Параметры:: style - требуемая длина текста, не null; locale - используемый язык, не null
Возвращает:: текстовое значение зоны, не null

getRules

public abstract ZoneRules getRules()

Получает правила часового пояса для данного идентификатора, позволяя выполнять вычисления.

Правила предоставляют функциональность, связанную с часовым поясом, такую как нахождение смещения для заданного момента или локального времени и даты.

Часовой пояс может быть недействительным, если он десериализован в среде выполнения Java, в которой не загружены те же правила, что и в среде выполнения Java, которая его сохранила. В этом случае вызов этого метода приведет к исключению ZoneRulesException.

Правила предоставляются ZoneRulesProvider. Расширенный поставщик может поддерживать динамическое обновление правил без перезапуска среды выполнения Java. В этом случае результат этого метода может со временем изменяться. Каждый отдельный вызов по-прежнему будет потокобезопасным.

ZoneOffset всегда возвращает набор правил, где смещение никогда не меняется.

Возвращает:: правила, не null
Исключения:: ZoneRulesException - если для данного идентификатора нет правил

normalized

public ZoneId normalized()

Нормализует идентификатор часового пояса, возвращая ZoneOffset, где это возможно.

Возвращает нормализованный ZoneId, который можно использовать вместо этого идентификатора. Результат будет иметь ZoneRules, эквивалентные тем, которые возвращаются этим объектом, однако идентификатор, возвращённый getId(), может быть другим.

Нормализация проверяет, имеют ли правила этого ZoneId фиксированное смещение. Если это так, то возвращается ZoneOffset, равное этому смещению. В противном случае возвращается this.

Возвращает:: уникальный идентификатор часового пояса, не null

equals

public boolean equals(Object obj)

Проверяет, равен ли этот идентификатор часового пояса другому идентификатору часового пояса.

Сравнение основано на идентификаторе.

Переопределяет:

equals в классе Object

Параметры:

obj - объект для проверки, null возвращает false

Возвращает:

true, если этот идентификатор равен другому идентификатору часового пояса

См. также:

hashCode

public int hashCode()

Хэш-код для этого идентификатора часового пояса.

Переопределяет:

hashCode в классе Object

Возвращает:

подходящий хэш-код

См. также:

toString

public String toString()

Выводит этот часовой пояс в виде String, используя идентификатор.

Переопределяет:: toString в классе Object
Возвращает:: строковое представление этого идентификатора часового пояса, не null

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/time/ZoneId.html