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

Это класс value-based; использование операций, чувствительных к идентичности (включая равенство ссылок (==), хэш-код по идентичности или синхронизация) на экземплярах 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). Она содержит идентификаторы регионов в формате '{область}/{город}', например '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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/ZoneId.html

Spec-Zone .ru
спецификации, руководства, описания, API