Top Description Fields Constructors Methods
java.time.zone

public abstract Class ZoneRulesProvider

extends Object
Class Inheritance
Known Direct Subclasses
java.time.zone.TzdbZoneRulesProvider
Imports
java.security.AccessController, .PrivilegedAction, java.time.ZoneId, .ZonedDateTime, java.util.ArrayList, .HashSet, .Iterator, .List, .NavigableMap, .Objects, .ServiceConfigurationError, .ServiceLoader, .Set, .Collections, java.util.concurrent.ConcurrentHashMap, .ConcurrentMap, .CopyOnWriteArrayList
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.

ZoneRulesProvider may be installed in an instance of the Java Platform as extension classes, that is, jar files placed into any of the usual extension directories. Installed providers are loaded using the service-provider loading facility defined by the ServiceLoader class. A ZoneRulesProvider identifies itself with a provider configuration file named java.time.zone.ZoneRulesProvider in the resource directory META-INF/services. The file should contain a line that specifies the fully qualified concrete zonerules-provider class name. Providers may also be made available by adding them to the class path or by registering themselves via registerProvider method.

The Java virtual machine has a default provider that provides zone rules for the time-zones defined by IANA Time Zone Database (TZDB). If the system property java.time.zone.DefaultZoneRulesProvider is defined then it is taken to be the fully-qualified name of a concrete ZoneRulesProvider class to be loaded as the default provider, using the system class loader. If this system property is not defined, a system-default provider will be loaded to serve as the default provider.

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.

Implementation Specification

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.

Providers are encouraged to implement a meaningful toString method.

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

Field Summary

Modifier and TypeField and Description
private static final CopyOnWriteArrayList<ZoneRulesProvider>
PROVIDERS

The set of loaded providers.

private static volatile Set<String>
ZONE_IDS

The zone ID data

private static final ConcurrentMap<String, ZoneRulesProvider>
ZONES

The lookup from zone ID to provider.

Constructor Summary

AccessConstructor and Description
protected
ZoneRulesProvider()

Constructor.

Method Summary

Modifier and TypeMethod and Description
public static Set<String>

Returns:

the unmodifiable set of zone IDs, not null
getAvailableZoneIds()

Gets the set of available zone IDs.

private static ZoneRulesProvider

Returns:

the provider, not null
getProvider(String
the zone ID as defined by ZoneId, not null
zoneId)

Gets the provider for the zone ID.

public static ZoneRules

Returns:

the rules, null if forCaching is true and this is a dynamic provider that wants to prevent caching in ZoneId, otherwise not null
getRules(String
the zone ID as defined by ZoneId, not null
zoneId, boolean
whether the rules are being queried for caching, true if the returned rules will be cached by ZoneId, false if they will be returned to the user without being cached in ZoneId
forCaching)

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.

public static NavigableMap<String, ZoneRules>

Returns:

a modifiable copy of the history of the rules for the ID, sorted from oldest to newest, not null
getVersions(String
the zone ID as defined by ZoneId, not null
zoneId)

Gets the history of rules for the zone ID.

Time-zones are defined by governments and change frequently.

protected boolean

Returns:

true if the rules were updated
provideRefresh()

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

protected abstract ZoneRules

Returns:

the rules, null if forCaching is true and this is a dynamic provider that wants to prevent caching in ZoneId, otherwise not null
provideRules(String
the zone ID as defined by ZoneId, not null
zoneId, boolean
whether the rules are being queried for caching, true if the returned rules will be cached by ZoneId, false if they will be returned to the user without being cached in ZoneId
forCaching)

SPI method to get the rules for the zone ID.

This loads the rules for the specified zone ID. The provider implementation must validate that the zone ID is valid and available, throwing a ZoneRulesException if it is not.

protected abstract NavigableMap<String, ZoneRules>

Returns:

a modifiable copy of the history of the rules for the ID, sorted from oldest to newest, not null
provideVersions(String
the zone ID as defined by ZoneId, not null
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.

protected abstract Set<String>

Returns:

the set of zone IDs being provided, not null
provideZoneIds()

SPI method to get the available zone IDs.

public static boolean

Returns:

true if the rules were updated
refresh()

Refreshes the rules from the underlying data provider.

public static void
registerProvider(ZoneRulesProvider
the provider to register, not null
provider)

Registers a zone rules provider.

private static synchronized void
registerProvider0(ZoneRulesProvider
the provider to register, not null
provider)

Registers the provider.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

PROVIDERSback to summary
private static final CopyOnWriteArrayList<ZoneRulesProvider> PROVIDERS

The set of loaded providers.

ZONE_IDSback to summary
private static volatile Set<String> ZONE_IDS

The zone ID data

ZONESback to summary
private static final ConcurrentMap<String, ZoneRulesProvider> ZONES

The lookup from zone ID to provider.

Constructor Detail

ZoneRulesProviderback to summary
protected ZoneRulesProvider()

Constructor.

Method Detail

getAvailableZoneIdsback to summary
public static Set<String> getAvailableZoneIds()

Gets the set of available zone IDs.

These IDs are the string form of a ZoneId.

Returns:Set<String>

the unmodifiable set of zone IDs, not null

getProviderback to summary
private static ZoneRulesProvider getProvider(String zoneId)

Gets the provider for the zone ID.

Parameters
zoneId:String

the zone ID as defined by ZoneId, not null

Returns:ZoneRulesProvider

the provider, not null

Exceptions
ZoneRulesException:
if the zone ID is unknown
getRulesback to summary
public static ZoneRules getRules(String zoneId, boolean forCaching)

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.

The caching flag is designed to allow provider implementations to prevent the rules being cached in ZoneId. Under normal circumstances, the caching of zone rules is highly desirable as it will provide greater performance. However, there is a use case where the caching would not be desirable, see provideRules.

Parameters
zoneId:String

the zone ID as defined by ZoneId, not null

forCaching:boolean

whether the rules are being queried for caching, true if the returned rules will be cached by ZoneId, false if they will be returned to the user without being cached in ZoneId

Returns:ZoneRules

the rules, null if forCaching is true and this is a dynamic provider that wants to prevent caching in ZoneId, otherwise not null

Exceptions
ZoneRulesException:
if rules cannot be obtained for the zone ID
getVersionsback to summary
public static NavigableMap<String, ZoneRules> getVersions(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:String

the zone ID as defined by ZoneId, not null

Returns:NavigableMap<String, ZoneRules>

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

Exceptions
ZoneRulesException:
if history cannot be obtained for the zone ID
provideRefreshback to summary
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:boolean

true if the rules were updated

Exceptions
ZoneRulesException:
if an error occurs during the refresh
provideRulesback to summary
protected abstract ZoneRules provideRules(String zoneId, boolean forCaching)

SPI method to get the rules for the zone ID.

This loads the rules for the specified zone ID. The provider implementation must validate that the zone ID is valid and available, throwing a ZoneRulesException if it is not. The result of the method in the valid case depends on the caching flag.

If the provider implementation is not dynamic, then the result of the method must be the non-null set of rules selected by the ID.

If the provider implementation is dynamic, then the flag gives the option of preventing the returned rules from being cached in ZoneId. When the flag is true, the provider is permitted to return null, where null will prevent the rules from being cached in ZoneId. When the flag is false, the provider must return non-null rules.

Parameters
zoneId:String

the zone ID as defined by ZoneId, not null

forCaching:boolean

whether the rules are being queried for caching, true if the returned rules will be cached by ZoneId, false if they will be returned to the user without being cached in ZoneId

Returns:ZoneRules

the rules, null if forCaching is true and this is a dynamic provider that wants to prevent caching in ZoneId, otherwise not null

Exceptions
ZoneRulesException:
if rules cannot be obtained for the zone ID
provideVersionsback to summary
protected abstract NavigableMap<String, ZoneRules> provideVersions(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 contain at least 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:String

the zone ID as defined by ZoneId, not null

Returns:NavigableMap<String, ZoneRules>

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

Exceptions
ZoneRulesException:
if history cannot be obtained for the zone ID
provideZoneIdsback to summary
protected abstract Set<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 zone ID.

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

Returns:Set<String>

the set of zone IDs being provided, not null

Exceptions
ZoneRulesException:
if a problem occurs while providing the IDs
refreshback to summary
public static boolean refresh()

Refreshes the rules from the underlying data provider.

This method allows an application to request that the providers check for any updates to the provided rules. After calling this method, the offset stored in any ZonedDateTime may be invalid for the zone ID.

Dynamic update of rules is a complex problem and most applications should not use this method or dynamic rules. To achieve dynamic rules, a provider implementation will have to be written as per the specification of this class. In addition, instances of ZoneRules must not be cached in the application as they will become stale. However, the boolean flag on provideRules(String, boolean) allows provider implementations to control the caching of ZoneId, potentially ensuring that all objects in the system see the new rules. Note that there is likely to be a cost in performance of a dynamic rules provider. Note also that no dynamic rules provider is in this specification.

Returns:boolean

true if the rules were updated

Exceptions
ZoneRulesException:
if an error occurs during the refresh
registerProviderback to summary
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:ZoneRulesProvider

the provider to register, not null

Exceptions
ZoneRulesException:
if a zone ID is already registered
registerProvider0back to summary
private static synchronized void registerProvider0(ZoneRulesProvider provider)

Registers the provider.

Parameters
provider:ZoneRulesProvider

the provider to register, not null

Exceptions
ZoneRulesException:
if unable to complete the registration