Класс 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 Time Zone Database (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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`protected void`	`finalize()`	Устарело, подлежит удалению: этот элемент API подлежит удалению в будущей версии. Финализация признана устаревшей и подлежит удалению в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс среды выполнения для этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ждать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ждать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ждать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.

Подробное описание полей

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 Time Zone Database (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.