public final class ZoneRulesGroup extends Object
Zone rule data is provided by organizations or groups. To manage this data each group is given a unique ID. One group is provided as standard - 'TZDB' - and more may be added.
The 'TZDB' group represents that data provided by the time-zone database as used in older versions of Java and many operating systems.
Other groups of zone rules can be developed and registered. Group IDs should be reverse domain names as with package names. Group IDs that do not contain a dot are reserved.
Each group will provide versioned sets of data for a number of geographical regions.
Instances of ZoneRulesGroup
manage the data via region and version IDs.
ZoneRulesGroup is thread-safe and immutable.
Rules may be registered at any time during the life of the application. No rules may be removed however, thus any rules obtained will remain valid.
The static methods of ZoneRulesGroup wrap a thread-safe map of groups. New groups and providers may safely be added during the lifetime of the application. To maintain data integrity, providers may not be removed during the lifetime of the application.
Modifier and Type | Method and Description |
---|---|
boolean |
equals(Object otherGroup)
Is this instance equal to that specified by comparing the group ID.
|
static List<ZoneRulesGroup> |
getAvailableGroups()
Gets the set of available zone rule groups.
|
Set<String> |
getAvailableVersionIDs()
Gets the set of available versions for this group.
|
static ZoneRulesGroup |
getGroup(String groupID)
Gets a group by ID, such as 'TZDB'.
|
String |
getID()
Gets the ID of the group, such as 'TZDB'.
|
String |
getLatestVersionID()
Gets the latest available version of the group's data.
|
String |
getLatestVersionID(String regionID)
Gets the latest available version of the group's data for a region.
|
String |
getLatestVersionIDValidFor(String regionID,
OffsetDateTime dateTime)
Finds the latest version ID that is valid for
|
static Set<String> |
getParsableIDs()
Gets a view of the complete set of parsable group:region IDs.
|
Set<String> |
getRegionIDs(String versionID)
Gets the set of available region IDs for this group that are valid for the specified version.
|
ZoneRules |
getRules(String regionID,
String versionID)
Gets the rules for the specified region#version ID combination.
|
ZoneRules |
getRulesValidFor(String regionID,
String versionID,
OffsetDateTime dateTime)
Gets the rules for the specified region and version ensuring that the rules
are valid for the date-time.
|
int |
hashCode()
A hash code for this object.
|
static boolean |
isValidGroupID(String groupID)
Checks if the group ID is valid.
|
boolean |
isValidRegionID(String regionID)
Checks if the region ID is valid.
|
boolean |
isValidRules(String regionID,
String versionID)
Checks if the region#version ID combination is valid.
|
static ZoneRulesGroup |
registerProvider(ZoneRulesDataProvider provider)
Registers a zone rules provider with this group.
|
String |
toString()
Returns a string representation of the group using the group ID.
|
public static boolean isValidGroupID(String groupID)
Which groups are available is dependent on the registered providers.
groupID
- the group ID, null returns falsepublic static ZoneRulesGroup getGroup(String groupID)
Which groups are available is dependent on the registered providers.
This method relies on time-zone data provider files. These are often loaded as jar files.
If no providers have been registered
or no
provider has been registered for the requested group then an exception is thrown.
groupID
- the group ID, not nullCalendricalException
- if the group ID is not foundpublic static List<ZoneRulesGroup> getAvailableGroups()
Which groups are available is dependent on the registered providers.
The returned groups will remain available and valid for the lifetime of the application as there is no way to deregister time-zone information. More groups may be added during the lifetime of the application, however the returned list will not be altered.
public static Set<String> getParsableIDs()
This returns the complete set of group:region IDs that can be parsed. The version is not included in the set for performance reasons. Each 'TZDB' ID will be included twice as the 'TZDB:' prefix is optional in parsing. For more detailed control, use the instance methods on this class.
For example, for the single time-zone of 'Europe/London' would contain:
Europe/London
TZDB:Europe/London
The returned set is a view of underlying state that may be changed by another thread. The underlying set is thread-safe, thus the view is thread-safe. However, check-then-act operations are potentially unsafe.
Since IDs are never deregistered, the set can only get larger. This means that it the caller can cache the set and its current size to use as an indication as to whether the contents have changed.
public static ZoneRulesGroup registerProvider(ZoneRulesDataProvider provider)
This adds a new provider to those currently available. Each provider is specific to one group, but may provide any number of regions and versions.
To ensure the integrity of time-zones already created, there is no way to deregister providers.
provider
- the provider to register, not nullCalendricalException
- if the group ID is invalidCalendricalException
- if the provider is already registeredpublic String getID()
public boolean isValidRules(String regionID, String versionID)
regionID
- the time-zone region ID, null returns falseversionID
- the time-zone version ID, null returns falsepublic ZoneRules getRules(String regionID, String versionID)
regionID
- the time-zone region ID, not nullversionID
- the time-zone version ID, not nullCalendricalException
- if the rules cannot be foundpublic ZoneRules getRulesValidFor(String regionID, String versionID, OffsetDateTime dateTime)
This method returns the rules matching the region and version providing that the date-time is valid. This checks both the region and version IDs for validity.
The returned rules will remain available and valid for the lifetime of the application as there is no way to deregister time-zone information. More rules may be added during the lifetime of the application, however the returned rules will not be altered.
regionID
- the time-zone region ID, not nullversionID
- the time-zone version ID, empty means floating version, not nulldateTime
- the date-time that must be valid, not nullCalendricalException
- if the rules cannot be foundpublic String getLatestVersionIDValidFor(String regionID, OffsetDateTime dateTime)
This method returns the latest version of the region rules where the date-time is valid. This checks the region for validity.
The returned version will remain valid for the lifetime of the application as there is no way to deregister time-zone information. If more time-zone information is added then a later version may become available.
regionID
- the time-zone region ID, not nulldateTime
- the date-time that must be valid, not nullCalendricalException
- if the region is unknownCalendricalException
- if the rules cannot be foundpublic Set<String> getAvailableVersionIDs()
The available versions are returned sorted from newest to oldest using
an ordering determined by a String
based sort.
The returned versions will remain available for the lifetime of the application as there is no way to deregister time-zone information. More regions may be added during the lifetime of the application, however the returned list will not be dynamically updated.
CalendricalException
- if the region ID is not foundpublic String getLatestVersionID()
The latest available version is determined by a String
based sort
of the versions.
The returned version will remain available for the lifetime of the application as there is no way to deregister time-zone information. More information may be added during the lifetime of the application, causing a later version to be available.
CalendricalException
- if the region ID is not foundpublic String getLatestVersionID(String regionID)
The latest available version is determined by a String
based sort
of the versions.
The returned version will remain available for the lifetime of the application as there is no way to deregister time-zone information. More information may be added during the lifetime of the application, causing a later version to be available.
regionID
- the time-zone region ID, not nullCalendricalException
- if the region ID is not foundpublic boolean isValidRegionID(String regionID)
The returned version will remain available for the lifetime of the application as there is no way to deregister time-zone information. More information may be added during the lifetime of the application, causing a later version to be available.
regionID
- the time-zone region ID, not nullCalendricalException
- if the region ID is not foundpublic Set<String> getRegionIDs(String versionID)
The available versions are returned sorted from oldest to newest using
an ordering determined by a String
based sort.
If the version is not found, an empty list is returned.
The returned regions will remain available for the lifetime of the application as there is no way to deregister time-zone information. More regions may be added during the lifetime of the application, however the returned list will not be altered.
versionID
- the time-zone version ID, empty means any version, not nullpublic boolean equals(Object otherGroup)
public int hashCode()
Copyright © 2014. All rights reserved.