java.time.zone

Class ZoneRulesProvider

java.lang.Object

java.time.zone.ZoneRulesProvider

public abstract class ZoneRulesProvider
extends java.lang.Object

Provider of time-zone rules to the system.

This class manages the configuration of time-zone rules. The static methods provide the public API that can be used to manage the providers. The abstract methods provide the SPI that allows rules to be provided.

Rules are looked up primarily by zone ID, as used by ZoneId. Only zone region IDs may be used, zone offset IDs are not used here.

Time-zone rules are political, thus the data can change at any time. Each provider will provide the latest rules for each zone ID, but they may also provide the history of how the rules changed.

Specification for implementors

This interface is a service provider that can be called by multiple threads. Implementations must be immutable and thread-safe.

Providers must ensure that once a rule has been seen by the application, the rule must continue to be available.

Many systems would like to update time-zone rules dynamically without stopping the JVM. When examined in detail, this is a complex problem. Providers may choose to handle dynamic updates, however the default provider does not.

Since:

1.8

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ZoneRulesProvider() Constructor.

Method Summary

Modifier and Type	Method and Description
static java.util.Set<java.lang.String>	getAvailableZoneIds() Gets the set of available zone IDs.
static ZoneRules	getRules(java.lang.String zoneId) Gets the rules for the zone ID.
static java.util.NavigableMap<java.lang.String,ZoneRules>	getVersions(java.lang.String zoneId) Gets the history of rules for the zone ID.
protected ZoneRulesProvider	provideBind(java.lang.String zoneId) SPI method to bind to the specified zone ID.
protected boolean	provideRefresh() SPI method to refresh the rules from the underlying data provider.
protected abstract ZoneRules	provideRules(java.lang.String regionId) SPI method to get the rules for the zone ID.
protected abstract java.util.NavigableMap<java.lang.String,ZoneRules>	provideVersions(java.lang.String zoneId) SPI method to get the history of rules for the zone ID.
protected abstract java.util.Set<java.lang.String>	provideZoneIds() SPI method to get the available zone IDs.
static boolean	refresh() Refreshes the rules from the underlying data provider.
static void	registerProvider(ZoneRulesProvider provider) Registers a zone rules provider.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ZoneRulesProvider

protected ZoneRulesProvider()

Constructor.

Method Detail

getAvailableZoneIds

public static java.util.Set<java.lang.String> getAvailableZoneIds()

Gets the set of available zone IDs.

These zone IDs are loaded and available for use by ZoneId.

Returns:

a modifiable copy of the set of zone IDs, not null

getRules

public static ZoneRules getRules(java.lang.String zoneId)

Gets the rules for the zone ID.

This returns the latest available rules for the zone ID.

This method relies on time-zone data provider files that are configured. These are loaded using a ServiceLoader.

Parameters:

zoneId - the zone region ID as used by ZoneId, not null

Returns:

the rules for the ID, not null

Throws:

ZoneRulesException - if the zone ID is unknown

getVersions

public static java.util.NavigableMap<java.lang.String,ZoneRules> getVersions(java.lang.String zoneId)

Gets the history of rules for the zone ID.

Time-zones are defined by governments and change frequently. This method allows applications to find the history of changes to the rules for a single zone ID. The map is keyed by a string, which is the version string associated with the rules.

The exact meaning and format of the version is provider specific. The version must follow lexicographical order, thus the returned map will be order from the oldest known rules to the newest available rules. The default 'TZDB' group uses version numbering consisting of the year followed by a letter, such as '2009e' or '2012f'.

Implementations must provide a result for each valid zone ID, however they do not have to provide a history of rules. Thus the map will always contain one element, and will only contain more than one element if historical rule information is available.

Parameters:

zoneId - the zone region ID as used by ZoneId, not null

Returns:

a modifiable copy of the history of the rules for the ID, sorted from oldest to newest, not null

Throws:

ZoneRulesException - if the zone ID is unknown

registerProvider

public static void registerProvider(ZoneRulesProvider provider)

Registers a zone rules provider.

This adds a new provider to those currently available. A provider supplies rules for one or more zone IDs. A provider cannot be registered if it supplies a zone ID that has already been registered. See the notes on time-zone IDs in ZoneId, especially the section on using the concept of a "group" to make IDs unique.

To ensure the integrity of time-zones already created, there is no way to deregister providers.

Parameters:

provider - the provider to register, not null

Throws:

ZoneRulesException - if a region is already registered

refresh

public static boolean refresh()

Refreshes the rules from the underlying data provider.

This method is an extension point that allows providers to refresh their rules dynamically at a time of the applications choosing. After calling this method, the offset stored in any ZonedDateTime may be invalid for the zone ID.

Dynamic behavior is entirely optional and most providers, including the default provider, do not support it.

Returns:

true if the rules were updated

Throws:

ZoneRulesException - if an error occurs during the refresh

provideZoneIds

protected abstract java.util.Set<java.lang.String> provideZoneIds()

SPI method to get the available zone IDs.

This obtains the IDs that this ZoneRulesProvider provides. A provider should provide data for at least one region.

The returned regions remain available and valid for the lifetime of the application. A dynamic provider may increase the set of regions as more data becomes available.

Returns:

the unmodifiable set of region IDs being provided, not null

provideBind

protected ZoneRulesProvider provideBind(java.lang.String zoneId)

SPI method to bind to the specified zone ID.

ZoneRulesProvider has a lookup from zone ID to provider. This method is used when building that lookup, allowing providers to insert a derived provider that is precisely tuned to the zone ID. This replaces two hash map lookups by one, enhancing performance.

This optimization is optional. Returning this is acceptable.

This implementation creates a bound provider that caches the rules from the underlying provider. The request to version history is forward on to the underlying. This is suitable for providers that cannot change their contents during the lifetime of the JVM.

Parameters:

zoneId - the zone region ID as used by ZoneId, not null

Returns:

the resolved provider for the ID, not null

Throws:

DateTimeException - if there is no provider for the specified group

provideRules

protected abstract ZoneRules provideRules(java.lang.String regionId)

SPI method to get the rules for the zone ID.

This loads the rules for the region and version specified. The version may be null to indicate the "latest" version.

Parameters:

regionId - the time-zone region ID, not null

Returns:

the rules, not null

Throws:

DateTimeException - if rules cannot be obtained

provideVersions

protected abstract java.util.NavigableMap<java.lang.String,ZoneRules> provideVersions(java.lang.String zoneId)

SPI method to get the history of rules for the zone ID.

This returns a map of historical rules keyed by a version string. The exact meaning and format of the version is provider specific. The version must follow lexicographical order, thus the returned map will be order from the oldest known rules to the newest available rules. The default 'TZDB' group uses version numbering consisting of the year followed by a letter, such as '2009e' or '2012f'.

Implementations must provide a result for each valid zone ID, however they do not have to provide a history of rules. Thus the map will always contain one element, and will only contain more than one element if historical rule information is available.

The returned versions remain available and valid for the lifetime of the application. A dynamic provider may increase the set of versions as more data becomes available.

Parameters:

zoneId - the zone region ID as used by ZoneId, not null

Returns:

a modifiable copy of the history of the rules for the ID, sorted from oldest to newest, not null

Throws:

ZoneRulesException - if the zone ID is unknown

provideRefresh

protected boolean provideRefresh()

SPI method to refresh the rules from the underlying data provider.

This method provides the opportunity for a provider to dynamically recheck the underlying data provider to find the latest rules. This could be used to load new rules without stopping the JVM. Dynamic behavior is entirely optional and most providers do not support it.

This implementation returns false.

Returns:

true if the rules were updated

Throws:

DateTimeException - if an error occurs during the refresh