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

Методы, объявленные в классе 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(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, что предотвратит кэширование правил в 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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/zone/ZoneRulesProvider.html