Класс ZoneRulesProvider

java.lang.Object
- java.time.zone.ZoneRulesProvider

public abstract class ZoneRulesProvider
extends Object

Поставщик правил часовых поясов для системы.

Этот класс управляет конфигурацией правил часовых поясов. Статические методы предоставляют общедоступный API, который можно использовать для управления поставщиками. Абстрактные методы предоставляют SPI, который позволяет предоставлять правила.

ZoneRulesProvider может быть установлен в экземпляре Java платформы в качестве расширяемых классов, то есть jar-файлов, помещённых в любые стандартные каталоги расширений. Установленные поставщики загружаются с помощью механизма загрузки поставщиков услуг, определенного классом ServiceLoader. ZoneRulesProvider идентифицирует себя с помощью файла конфигурации поставщика, названного java.time.zone.ZoneRulesProvider в каталоге ресурсов META-INF/services. Файл должен содержать строку, которая указывает полное имя класса конкретного поставщика zonerules-provider. Поставщики также могут быть доступны путём добавления их в путь к классам или путём регистрации их через метод registerProvider(java.time.zone.ZoneRulesProvider).

В виртуальной машине Java есть поставщик по умолчанию, который предоставляет правила часовых поясов для часовых поясов, определённых базой данных часовых поясов IANA (TZDB). Если системная переменная java.time.zone.DefaultZoneRulesProvider определена, то она рассматривается как полное имя конкретного класса ZoneRulesProvider, который нужно загрузить в качестве поставщика по умолчанию, используя системный загрузчик классов. Если эта системная переменная не определена, то будет загружен системный поставщик по умолчанию, который послужит поставщиком по умолчанию.

Правила ищутся в первую очередь по идентификатору часового пояса, как используется в ZoneId. Используются только идентификаторы регионов часовых поясов, идентификаторы смещений часовых поясов здесь не используются.

Правила часовых поясов являются политическими, поэтому данные могут меняться в любое время. Каждый поставщик будет предоставлять последние правила для каждого идентификатора часового пояса, но он также может предоставить историю изменений правил.

Требования к реализации:

Этот интерфейс является поставщиком услуг, к которому могут обращаться несколько потоков. Реализации должны быть неизменяемыми и потокобезопасными.

Поставщики должны гарантировать, что после того, как правило было замечено приложением, правило должно продолжать быть доступным.

Поставщикам рекомендуется реализовать осмысленный метод toString.

Многие системы хотели бы динамически обновлять правила часовых поясов без остановки JVM. При детальном рассмотрении это сложная задача. Поставщики могут выбрать, как обрабатывать динамические обновления, однако поставщик по умолчанию этого не делает.

C тех пор как:

1.8

Конструкторы

Модификатор	Конструктор и описание
`protected`	`ZoneRulesProvider()` Конструктор.

Методы

Модификатор и тип	Метод и описание
`static Set<String>`	`getAvailableZoneIds()` Возвращает набор доступных идентификаторов часовых поясов.
`static ZoneRules`	`getRules(String zoneId, boolean forCaching)` Возвращает правила для идентификатора часового пояса.
`static NavigableMap<String,ZoneRules>`	`getVersions(String zoneId)` Возвращает историю правил для идентификатора часового пояса.
`protected boolean`	`provideRefresh()` Метод SPI для обновления правил из базового поставщика данных.
`protected abstract ZoneRules`	`provideRules(String zoneId, boolean forCaching)` Метод SPI для получения правил для идентификатора часового пояса.
`protected abstract NavigableMap<String,ZoneRules>`	`provideVersions(String zoneId)` Метод SPI для получения истории правил для идентификатора часового пояса.
`protected abstract Set<String>`	`provideZoneIds()` Метод SPI для получения доступных идентификаторов часовых поясов.
`static boolean`	`refresh()` Обновляет правила из базового поставщика данных.
`static void`	`registerProvider(ZoneRulesProvider provider)` Регистрирует поставщик правил часовых поясов.

Методы, унаследованные от класса java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Конструкторы

ZoneRulesProvider

protected ZoneRulesProvider()

Конструктор.

Методы

getAvailableZoneIds

public static Set<String> getAvailableZoneIds()

Возвращает набор доступных идентификаторов зон.

Эти идентификаторы — строковая форма ZoneId.

Возвращает:: изменяемую копию набора идентификаторов зон, не null

getRules

public static ZoneRules getRules(String zoneId,
                                 boolean forCaching)

Получает правила для идентификатора зоны.

Возвращает самые последние доступные правила для идентификатора зоны.

Этот метод использует файлы с данными о часовых поясах, которые настроены. Они загружаются с помощью ServiceLoader.

Флаг кэширования предназначен для того, чтобы реализации поставщиков предотвращали кэширование правил в ZoneId. В нормальных обстоятельствах кэширование правил зон желательно, так как это повысит производительность. Однако есть случай, когда кэширование нежелательно, см. provideRules(java.lang.String, boolean).

Параметры:: zoneId — идентификатор зоны, определённый ZoneId, не null; forCaching — указывается ли запрос правил для кэширования, true, если возвращаемые правила будут кэшированы ZoneId, false, если они будут возвращены пользователю без кэширования в ZoneId
Возвращает:: правила, null, если forCaching true, и это динамический поставщик, который хочет предотвратить кэширование в ZoneId, в противном случае не null
Исключение:: ZoneRulesException — если правила для идентификатора зоны получить невозможно

getVersions

public static NavigableMap<String,ZoneRules> getVersions(String zoneId)

Возвращает историю правил для идентификатора зоны.

Часовые пояса определяются правительствами и часто меняются. Этот метод позволяет приложениям найти историю изменений правил для отдельного идентификатора зоны. Карта имеет ключи в виде строк, которые представляют собой строку версии, связанную с правилами.

Точное значение и формат версии зависят от поставщика. Версия должна следовать лексикографическому порядку, поэтому возвращаемая карта будет отсортирована от старейших известных правил к самым новым доступным правилам. По умолчанию группа 'TZDB' использует нумерацию версий, состоящую из года и буквы, например, '2009e' или '2012f'.

Реализации должны предоставлять результат для каждого допустимого идентификатора зоны, но они не обязаны предоставлять историю правил. Таким образом, карта всегда будет содержать один элемент и будет содержать более одного элемента только если есть информация об исторических правилах.

Параметры:: zoneId — идентификатор зоны, определённый ZoneId, не null
Возвращает:: изменяемую копию истории правил для идентификатора, отсортированную от старейших к новейшим, не null
Исключение:: ZoneRulesException — если историю для идентификатора зоны получить невозможно

registerProvider

public static void registerProvider(ZoneRulesProvider provider)

Регистрирует поставщика правил зон.

Это добавляет нового поставщика к тем, которые в настоящее время доступны. Поставщик предоставляет правила для одного или нескольких идентификаторов зон. Поставщик не может быть зарегистрирован, если он предоставляет идентификатор зоны, который уже был зарегистрирован. См. примечания об идентификаторах часовых поясов в ZoneId, особенно раздел об использовании понятия «группа» для уникализации идентификаторов.

Чтобы обеспечить целостность уже созданных часовых поясов, нет способа отказаться от регистрации поставщиков.

Параметры:: provider — регистрируемый поставщик, не null
Исключение:: ZoneRulesException — если идентификатор зоны уже зарегистрирован

refresh

public static boolean refresh()

Обновляет правила из базового поставщика данных.

Этот метод позволяет приложению запросить поставщиков проверить наличие обновлений предоставленных правил. После вызова этого метода смещение, хранящееся в любом ZonedDateTime, может быть недействительным для идентификатора зоны.

Динамическое обновление правил — сложная проблема, и большинство приложений не должны использовать этот метод или динамические правила. Для достижения динамических правил реализация поставщика должна быть написана в соответствии со спецификацией этого класса. Кроме того, экземпляры ZoneRules не должны кэшироваться в приложении, поскольку они устареют. Однако флаг булевого типа в provideRules(String, boolean) позволяет реализациям поставщиков контролировать кэширование ZoneId, потенциально гарантируя, что все объекты в системе увидят новые правила. Обратите внимание, что динамический поставщик правил, вероятно, повлияет на производительность. Также обратите внимание, что ни один динамический поставщик правил не указан в данной спецификации.

Возвращает:: true, если правила были обновлены
Исключение:: ZoneRulesException — если при обновлении произошла ошибка

provideZoneIds

protected abstract Set<String> provideZoneIds()

Метод SPI для получения доступных идентификаторов зон.

Это получает идентификаторы, которые предоставляет этот ZoneRulesProvider. Поставщик должен предоставлять данные хотя бы для одного идентификатора зоны.

Возвращаемые идентификаторы зон остаются доступными и действительными в течение всего жизненного цикла приложения. Динамический поставщик может увеличивать набор идентификаторов по мере получения дополнительных данных.

Возвращает:: набор идентификаторов зон, предоставляемых поставщиком, не null
Исключение:: ZoneRulesException — если при получении идентификаторов произошла проблема

provideRules

protected abstract ZoneRules provideRules(String zoneId,
                                          boolean forCaching)

Метод SPI для получения правил для идентификатора зоны.

Загружает правила для указанного идентификатора зоны. Реализация поставщика должна проверять, является ли идентификатор зоны допустимым и доступным, выбросив ZoneRulesException в противном случае. Результат метода в случае допустимости зависит от флага кэширования.

Если реализация поставщика не динамическая, то результатом метода должен быть не нулевой набор правил, выбранных по идентификатору.

Если реализация поставщика динамическая, флаг даёт возможность предотвратить кэширование возвращаемых правил в ZoneId. Когда флаг true, поставщик имеет право возвратить null, где null предотвратит кэширование правил в ZoneId. Когда флаг false, поставщик должен возвращать не нулевые правила.

Параметры:: zoneId — идентификатор зоны, определённый ZoneId, не null; forCaching — указывается ли запрос правил для кэширования, true, если возвращаемые правила будут кэшированы ZoneId, false, если они будут возвращены пользователю без кэширования в ZoneId
Возвращает:: правила, null, если forCaching true, и это динамический поставщик, который хочет предотвратить кэширование в ZoneId, в противном случае не null
Исключение:: ZoneRulesException — если правила для идентификатора зоны получить невозможно

provideVersions

protected abstract NavigableMap<String,ZoneRules> provideVersions(String zoneId)

Метод SPI для получения истории правил для идентификатора зоны.

Возвращает карту исторических правил, ключами которой являются строки версий. Точное значение и формат версии зависят от поставщика. Версия должна следовать лексикографическому порядку, поэтому возвращаемая карта будет отсортирована от старейших известных правил к самым новым доступным правилам. По умолчанию группа 'TZDB' использует нумерацию версий, состоящую из года и буквы, например, '2009e' или '2012f'.

Реализации должны предоставлять результат для каждого допустимого идентификатора зоны, но они не обязаны предоставлять историю правил. Таким образом, карта будет содержать по крайней мере один элемент и будет содержать более одного элемента только если есть информация об исторических правилах.

Возвращаемые версии остаются доступными и действительными в течение всего жизненного цикла приложения. Динамический поставщик может увеличивать набор версий по мере получения дополнительных данных.

Параметры:: zoneId — идентификатор зоны, определённый ZoneId, не null
Возвращает:: изменяемую копию истории правил для идентификатора, отсортированную от старейших к новейшим, не null
Исключение:: ZoneRulesException — если историю для идентификатора зоны получить невозможно

provideRefresh

protected boolean provideRefresh()

Метод SPI для обновления правил из базового поставщика данных.

Этот метод предоставляет возможность поставщику динамически повторно проверять базовый поставщик данных, чтобы найти самые последние правила. Это может быть использовано для загрузки новых правил без остановки JVM. Динамическое поведение полностью необязательно, и большинство поставщиков его не поддерживают.

Эта реализация возвращает false.

Возвращает:: true, если правила были обновлены
Исключение:: ZoneRulesException — если при обновлении произошла ошибка

© 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.