模块  java.base
软件包  java.time.zone

Class ZoneRulesProvider

  • public abstract class ZoneRulesProviderextends Object
    为系统提供时区规则。

    此类管理时区规则的配置。 静态方法提供可用于管理提供程序的公共API。 抽象方法提供允许提供规则的SPI。

    ZoneRulesProvider可以作为扩展类安装在Java平台的实例中，即放置在任何常用扩展目录中的jar文件。 使用ServiceLoader类定义的服务提供者加载工具加载已安装的提供程序。 ZoneRulesProvider使用资源目录META-INF/services名为java.time.zone.ZoneRulesProvider的提供程序配置文件标识自身。 该文件应包含一行，该行指定完全限定的具体zonerules-provider类名。 也可以通过将提供者添加到类路径或通过registerProvider(java.time.zone.ZoneRulesProvider)方法注册自己来提供提供者 。

    Java虚拟机具有默认提供程序，该提供程序为IANA时区数据库（TZDB）定义的时区提供区域规则。 如果定义了系统属性java.time.zone.DefaultZoneRulesProvider ，那么它将被视为使用系统类加载器作为默认提供程序加载的具体ZoneRulesProvider类的完全限定名称。 如果未定义此系统属性，则将加载系统默认提供程序以用作默认提供程序。

    规则主要由区域ID查找，如ZoneId所使用。 可以仅使用区域ID，这里不使用区域偏移ID。

    时区规则是政治性的，因此数据可以随时改变。 每个提供商都将为每个区域ID提供最新规则，但它们也可能提供规则更改的历史记录。

    实现要求：
    此接口是可由多个线程调用的服务提供程序。 实现必须是不可变的和线程安全的。

    提供商必须确保一旦应用程序看到规则，该规则必须继续可用。

    鼓励提供商实施有意义的toString方法。

    许多系统都希望在不停止JVM的情况下动态更新时区规则。 详细检查时，这是一个复杂的问题。 提供商可以选择处理动态更新，但默认提供商不会。

    从以下版本开始：
    1.8

    • 构造方法详细信息

      • ZoneRulesProvider

        protected ZoneRulesProvider()
        构造函数。

    • 方法详细信息

      • getAvailableZoneIds

        public static Set<String> getAvailableZoneIds()
        获取可用区域ID的集合。

        这些ID是ZoneId的字符串形式。

        结果
        不可修改的区域ID集，不为null

      • getRules

        public static ZoneRules getRules​(String zoneId,                                 boolean forCaching)
        获取区域ID的规则。

        这将返回区域ID的最新可用规则。

        此方法依赖于已配置的时区数据提供程序文件。 这些是使用ServiceLoader加载的。

        缓存标志旨在允许提供程序实现阻止在ZoneId中缓存规则。 在正常情况下，区域规则的缓存是非常需要的，因为它将提供更好的性能。 但是，有一个用例，其中不需要缓存，请参阅provideRules(java.lang.String, boolean) 。

        参数
        zoneId - 由 ZoneId定义的区域ID，不为空
        forCaching - 是否正在查询缓存规则，如果返回的规则将由 ZoneId缓存， ZoneId true;如果将在 ZoneId中缓存， ZoneId返回给用户， ZoneId
        结果
        规则，如果 forCaching为true， forCaching null，这是一个动态提供程序，希望在 ZoneId阻止缓存，否则不为null
        异常
        ZoneRulesException - 如果无法获取区域ID的规则

      • getVersions

        public static NavigableMap<String,​ZoneRules> getVersions​(String zoneId)
        获取区域ID的规则历史记录。

        时区由政府定义并经常变化。 此方法允许应用程序查找单个区域ID的规则更改历史记录。 地图由字符串键控，该字符串是与规则关联的版本字符串。

        版本的确切含义和格式是提供者特定的。 版本必须遵循词典顺序，因此返回的地图将从最早的已知规则到最新的可用规则进行排序。 默认的“TZDB”组使用的版本编号包括年份后跟一个字母，例如“2009e”或“2012f”。

        实现必须为每个有效的区域ID提供结果，但是它们不必提供规则历史记录。 因此，地图将始终包含一个元素，并且如果历史规则信息可用，则仅包含多个元素。

        参数
        zoneId - 由 ZoneId定义的区域ID，不为空
        结果
        ID的规则历史的可修改副本，从最旧到最新排序，不为空
        异常
        ZoneRulesException - 如果无法获取区域ID的历史记录

      • registerProvider

        public static void registerProvider​(ZoneRulesProvider provider)
        注册区域规则提供程序。

        这为当前可用的添加提供了新的提供程序。 提供商提供一个或多个区域ID的规则。 如果提供商提供已注册的区域ID，则无法注册。 请参阅ZoneId中有关时区ID的说明 ，尤其是使用“组”概念使ID唯一的部分。

        为确保已创建的时区的完整性，无法取消注册提供程序。

        参数
        provider - 要注册的提供程序，而不是null
        异常
        ZoneRulesException - 如果已注册区域ID

      • refresh

        public static boolean refresh()
        从基础数据提供程序刷新规则。

        此方法允许应用程序请求提供程序检查所提供规则的任何更新。 调用此方法后，存储在任何ZonedDateTime中的偏移可能对区域ID无效。

        动态更新规则是一个复杂的问题，大多数应用程序不应使用此方法或动态规则。 要实现动态规则，必须根据此类的规范编写提供程序实现。 此外， ZoneRules实例不得在应用程序中缓存，因为它们将变得陈旧。 但是， provideRules(String, boolean)上的布尔标志允许提供程序实现控制ZoneId的高速缓存， ZoneId可能确保系统中的所有对象都能看到新规则。 请注意，动态规则提供程序的性能可能会有成本。 另请注意，此规范中没有动态规则提供程序。

        结果
        如果规则已更新，则为true
        异常
        ZoneRulesException - 如果在刷新期间发生错误

      • provideZoneIds

        protected abstract Set<String> provideZoneIds()
        SPI方法获取可用的区域ID。

        这将获得此ZoneRulesProvider提供的ID。 提供者应提供至少一个区域ID的数据。

        返回的区域ID在应用程序的生命周期内仍然可用且有效。 随着更多数据变得可用，动态提供者可以增加ID集。

        结果
        提供的区域ID集合，而不是null
        异常
        ZoneRulesException - 如果在提供ID时出现问题

      • provideRules

        protected abstract ZoneRules provideRules​(String zoneId,                                          boolean forCaching)
        SPI方法获取区域ID的规则。

        这会加载指定区域ID的规则。 提供程序实现必须验证区域ID是否有效且可用，如果不是，则抛出ZoneRulesException 。 有效情况下方法的结果取决于缓存标志。

        如果提供程序实现不是动态的，则方法的结果必须是ID选择的非空规则集。

        如果提供程序实现是动态的，则该标志提供了阻止返回的规则在ZoneId中缓存的选项 。 当该标志为true时，允许提供程序返回null，其中null将阻止在ZoneId中缓存规则。 当标志为false时，提供程序必须返回非空规则。

        参数
        zoneId - 由 ZoneId定义的区域ID，不为空
        forCaching - 是否正在查询缓存规则，如果返回的规则将由 ZoneId缓存， ZoneId true;如果将在 ZoneId中缓存， ZoneId返回给用户， ZoneId
        结果
        规则，如果 forCaching为真， forCaching null，这是一个想要在 ZoneId阻止缓存的动态提供程序，否则不为null
        异常
        ZoneRulesException - 如果无法获取区域ID的规则

      • provideVersions

        protected abstract NavigableMap<String,​ZoneRules> provideVersions​(String zoneId)
        SPI方法获取区域ID的规则历史。

        这将返回由版本字符串键入的历史规则的映射。 版本的确切含义和格式是提供者特定的。 版本必须遵循词典顺序，因此返回的地图将从最早的已知规则到最新的可用规则进行排序。 默认的“TZDB”组使用的版本编号包括年份后跟一个字母，例如“2009e”或“2012f”。

        实现必须为每个有效的区域ID提供结果，但是它们不必提供规则历史记录。 因此，地图将包含至少一个元素，并且如果历史规则信息可用，则仅包含多个元素。

        返回的版本在应用程序的生命周期内仍然可用且有效。 随着更多数据变得可用，动态提供者可以增加版本集。

        参数
        zoneId - 由 ZoneId定义的区域ID，不为空
        结果
        ID的规则历史的可修改副本，从最旧到最新排序，不为空
        异常
        ZoneRulesException - 如果无法获取区域ID的历史记录

      • provideRefresh

        protected boolean provideRefresh()
        SPI方法从底层数据提供程序刷新规则。

        此方法为提供程序提供了动态重新检查基础数据提供程序以查找最新规则的机会。 这可以用于在不停止JVM的情况下加载新规则。 动态行为完全是可选的，大多数提供商都不支持它。

        此实现返回false。

        结果
        如果规则已更新，则为true
        异常
        ZoneRulesException - 如果在刷新期间发生错误