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

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

Если реализация поставщика динамична, то флаг предоставляет возможность предотвращения кэширования возвращаемых правил в 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, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/time/zone/ZoneRulesProvider.html