Class ZoneRulesGroup
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.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final String
The zone rules group ID, such as 'TZDB'.private static final ConcurrentMap<String,
ZoneRulesGroup> The zone rule groups.The zone IDs.private static final Pattern
Group ID pattern.private static final Pattern
Version ID pattern.private AtomicReference<TreeMap<String,
ZoneRulesVersion>> The versions and rules. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
Is this instance equal to that specified by comparing the group ID.static List<ZoneRulesGroup>
Gets the set of available zone rule groups.Gets the set of available versions for this group.static ZoneRulesGroup
Gets a group by ID, such as 'TZDB'.getID()
Gets the ID of the group, such as 'TZDB'.Gets the latest available version of the group's data.getLatestVersionID
(String regionID) Gets the latest available version of the group's data for a region.getLatestVersionIDValidFor
(String regionID, OffsetDateTime dateTime) Finds the latest version ID that is valid forGets a view of the complete set of parsable group:region IDs.getRegionIDs
(String versionID) Gets the set of available region IDs for this group that are valid for the specified version.Gets the rules for the specified region#version ID combination.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.private void
registerProvider0
(ZoneRulesDataProvider provider) Registers a zone rules provider with this group.toString()
Returns a string representation of the group using the group ID.
-
Field Details
-
PATTERN_GROUP
Group ID pattern. -
PATTERN_VERSION
Version ID pattern. -
IDS
The zone IDs. Should not be empty. -
GROUPS
The zone rule groups. Should not be empty. -
groupID
The zone rules group ID, such as 'TZDB'. -
versions
The versions and rules.
-
-
Constructor Details
-
ZoneRulesGroup
Constructor.- Parameters:
groupID
- the group ID, not null- Throws:
CalendricalException
- if the group ID is invalid
-
-
Method Details
-
isValidGroupID
Checks if the group ID is valid.Which groups are available is dependent on the registered providers.
- Parameters:
groupID
- the group ID, null returns false- Returns:
- true if the group ID is valid
-
getGroup
Gets a group by ID, such as 'TZDB'.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.- Parameters:
groupID
- the group ID, not null- Returns:
- the zone rules group, never null
- Throws:
CalendricalException
- if the group ID is not found
-
getAvailableGroups
Gets the set of available zone rule groups.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.
- Returns:
- an unsorted, independent, modifiable list of available groups, never null
-
getParsableIDs
Gets a view of the complete set of parsable group:region IDs.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.
- Returns:
- an unmodifiable set of parsable group:region IDs, never null
-
registerProvider
Registers a zone rules provider with this group.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.
- Parameters:
provider
- the provider to register, not null- Returns:
- the rules group, never null
- Throws:
CalendricalException
- if the group ID is invalidCalendricalException
- if the provider is already registered
-
registerProvider0
Registers a zone rules provider with this group.- Parameters:
provider
- the provider to register, not null
-
getID
Gets the ID of the group, such as 'TZDB'.- Returns:
- the ID of the group, never null
-
isValidRules
Checks if the region#version ID combination is valid.- Parameters:
regionID
- the time-zone region ID, null returns falseversionID
- the time-zone version ID, null returns false- Returns:
- true if the version ID is valid
-
getRules
Gets the rules for the specified region#version ID combination.- Parameters:
regionID
- the time-zone region ID, not nullversionID
- the time-zone version ID, not null- Returns:
- the matched zone rules, never null
- Throws:
CalendricalException
- if the rules cannot be found
-
getRulesValidFor
Gets the rules for the specified region and version ensuring that the rules are valid for the date-time.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.
- Parameters:
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 null- Returns:
- the matched zone rules, never null
- Throws:
CalendricalException
- if the rules cannot be found
-
getLatestVersionIDValidFor
Finds the latest version ID that is valid forThis 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.
- Parameters:
regionID
- the time-zone region ID, not nulldateTime
- the date-time that must be valid, not null- Returns:
- the matched zone rules, never null
- Throws:
CalendricalException
- if the region is unknownCalendricalException
- if the rules cannot be found
-
getAvailableVersionIDs
Gets the set of available versions for this group.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.
- Returns:
- the version IDs sorted from newest to oldest, unmodifiable, never null
- Throws:
CalendricalException
- if the region ID is not found
-
getLatestVersionID
Gets the latest available version of the group's data.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.
- Returns:
- the latest version ID for the group, never null
- Throws:
CalendricalException
- if the region ID is not found
-
getLatestVersionID
Gets the latest available version of the group's data for a region.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.
- Parameters:
regionID
- the time-zone region ID, not null- Returns:
- the latest version ID for the region, never null
- Throws:
CalendricalException
- if the region ID is not found
-
isValidRegionID
Checks if the region ID is valid.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.
- Parameters:
regionID
- the time-zone region ID, not null- Returns:
- true if the region ID is valid for at least one version
- Throws:
CalendricalException
- if the region ID is not found
-
getRegionIDs
Gets the set of available region IDs for this group that are valid for the specified version.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.
- Parameters:
versionID
- the time-zone version ID, empty means any version, not null- Returns:
- the region IDs, unmodifiable, never null
-
equals
Is this instance equal to that specified by comparing the group ID. -
hashCode
public int hashCode()A hash code for this object. -
toString
Returns a string representation of the group using the group ID.
-