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

С:

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 не должны кэшироваться в приложении, так как они устареют. Однако флаг в методе 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 если это не так. Результат метода в допустимом случае зависит от флага кеширования.

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

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

Параметры:: 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, 2023, 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/21/docs/api/java.base/java/time/zone/ZoneRulesProvider.html