Класс ZoneRulesProvider

java.lang.Object

java.time.zone.ZoneRulesProvider

public abstract class ZoneRulesProvider extends Object

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

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

ZoneRulesProvider может быть установлен в экземпляре Java Platform в виде расширяющих классов, то есть 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

Краткое описание конструкторов

ZoneRulesProvider()

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

Краткое описание методов

Модификатор и тип	Метод	Описание
`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 не должны кэшироваться в приложении, так как они устареют. Однако флаг boolean в 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, 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/zone/ZoneRulesProvider.html