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

Это класс значение; использование операций, чувствительных к идентификатору (включая равенство ссылок (==), хэш-код по идентификатору или синхронизацию) над экземплярами ZoneId может привести к непредсказуемым результатам и следует избегать. Для сравнений следует использовать метод equals.

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

Поля

Модификатор и тип	Поле и описание
`static 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 для «Тихоокеанского стандартного времени» и PDT для «Тихоокеанского летнего времени». Эти сокращения не уникальны и поэтому не могут использоваться в качестве идентификаторов. Этот метод позволяет настроить и повторно использовать карту строк к часовому поясу в приложении.

Параметры:: 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)

Получает текстовое представление зоны, например, «Время Великобритании» или «+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)

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

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

Переопределяет:: equals в классе Object
Параметры:: obj - проверяемый объект, null возвращает false
Возвращает:: true, если это идентично другому идентификатору часового пояса
См. также:: Object.hashCode(), HashMap

hashCode

public int hashCode()

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

Переопределяет:: hashCode в классе Object
Возвращает:: подходящий код хэша
См. также:: Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

public String toString()

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

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

© 1993, 2020, 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.