Module  java.base
软件包  java.time.zone

Class ZoneRulesProvider


  • public abstract class ZoneRulesProvider
extends Object
    提供给系统的时区规则。

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

    ZoneRulesProvider可以作为扩展类安装在Java Platform的实例中，也就是将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集，不为空

      • 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
        结果
        规则，如果为 forCaching则为null，这是一个动态提供程序，希望在 ZoneId防止缓存，否则不为空
        异常
        ZoneRulesException - 如果无法获取区域ID的规则

      • getVersions

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

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

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

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

        参数
        zoneId - 由 ZoneId定义的区域ID，不为空
        结果
        ID的规则的历史的可修改副本，从最旧到最新排序，不为null
        异常
        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集合，不为空
        异常
        ZoneRulesException - 提供ID时是否出现问题

      • provideRules

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

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

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

        如果提供程序实现是动态的，那么该标志可以选择防止返回的规则在ZoneId中被缓存。 当标志为真时，允许提供者返回null，其中null将阻止规则在ZoneId被缓存。 当标志为false时，提供者必须返回非空规则。

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

      • provideVersions

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

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

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

        返回的版本在应用程序的生命周期内保持可用且有效。 动态提供程序可能会随着更多数据可用而增加版本集。

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

      • provideRefresh

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

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

        此实现返回false。

        结果
        如果规则更新，则为true
        异常
        ZoneRulesException - 如果在刷新过程中发生错误