Класс 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, является ли другой объект «равным» этому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API планируется удалить в будущей версии. Финализация объявлена устаревшей и планируется к удалению в одном из следующих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает значение хеш-кода для этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо истечения заданного времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо истечения заданного времени.

Подробное описание конструкторов

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.