Класс ZoneId

java.lang.Object

java.time.ZoneId

Все реализованные интерфейсы:: Serializable

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

public abstract class ZoneId extends Object implements Serializable

Идентификатор часового пояса, например 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 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). В ней идентификаторы регионов имеют вид '{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 Runtime, который не загрузил те же правила, что и Java Runtime, который его сохранил. В этом случае вызов этого метода приведет к выбрасыванию ZoneRulesException.

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

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

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

normalized

public ZoneId normalized()

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

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

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

Возвращает:: уникальный идентификатор часового пояса, не 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, используя идентификатор.

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

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