Класс 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`, используя его идентификатор.

Методы, объявленные в классе 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 по его идентификатору, используя карту псевдонимов в дополнение к стандартным идентификаторам часовых поясов.

Многие пользователи часовых поясов используют короткие сокращения, например 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. Если идентификатор равен 'Z' или начинается с '+' или '-', возвращается ZoneOffset. Результатом всегда является допустимый идентификатор, для которого можно получить 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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/ZoneId.html