- java.lang.Object
-
- java.time.zone.ZoneRulesProvider
-
public abstract class ZoneRulesProvider extends 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
-
-
构造方法摘要
构造方法 变量 构造器 描述 protected
ZoneRulesProvider()
构造函数。
-
方法摘要
所有方法 静态方法 实例方法 抽象方法 具体的方法 变量和类型 方法 描述 static Set<String>
getAvailableZoneIds()
获取可用区域ID的集合。static ZoneRules
getRules(String zoneId, boolean forCaching)
获取区域ID的规则。static NavigableMap<String,ZoneRules>
getVersions(String zoneId)
获取区域ID的规则历史记录。protected boolean
provideRefresh()
SPI方法从底层数据提供程序刷新规则。protected abstract ZoneRules
provideRules(String zoneId, boolean forCaching)
SPI方法获取区域ID的规则。protected abstract NavigableMap<String,ZoneRules>
provideVersions(String zoneId)
SPI方法获取区域ID的规则历史。protected abstract Set<String>
provideZoneIds()
SPI方法获取可用的区域ID。static boolean
refresh()
从基础数据提供程序刷新规则。static void
registerProvider(ZoneRulesProvider provider)
注册区域规则提供程序。
-
-
-
方法详细信息
-
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
- 如果在刷新期间发生错误
-
-