Класс 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. При детальном рассмотрении это сложная задача. Поставщики могут выбрать способ обработки динамических обновлений, однако поставщик по умолчанию этого не делает.

С:
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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/zone/ZoneRulesProvider.html

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