Класс 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 с неполной информацией о часовых поясах.

Это класс value-based; программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать экземпляры для синхронизации, иначе может произойти непредсказуемое поведение. Например, в будущей версии синхронизация может завершиться ошибкой. Для сравнения следует использовать метод 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 2005r и более поздним версиям, где 'EST', 'MST' и 'HST' сопоставляются с идентификаторами, не включающими летнее время.

Эта карта сопоставляет значения следующим образом:

EST - -05:00
HST - -10:00
MST - -07:00
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
IET - America/Indiana/Indianapolis
IST - Asia/Kolkata
JST - Asia/Tokyo
MIT - Pacific/Apia
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. 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). Она имеет идентификаторы регионов в форме '{область}/{город}', такие как '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 Runtime, в котором загружены не те же правила, что и в Java Runtime, который его сохранил. В этом случае вызов этого метода выбросит ZoneRulesException.

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

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

Возвращает:: правила, не null
Выбрасывает:: ZoneRulesException - если правила недоступны для этого идентификатора

normalized

public ZoneId normalized()

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

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

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

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

equals

public boolean equals(Object obj)

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

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

Overrides:

equals в классе Object

Parameters:

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

Returns:

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

See Also:

hashCode

public int hashCode()

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

Overrides:

hashCode в классе Object

Returns:

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

See Also:

toString

public String toString()

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

Overrides:: toString в классе Object
Returns:: строковое представление этого идентификатора часового пояса, не null

© 1993, 2023, 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/21/docs/api/java.base/java/time/ZoneId.html