Class ZoneRulesGroup
- java.lang.Object
-
- javax.time.calendar.zone.ZoneRulesGroup
-
public final class ZoneRulesGroup extends java.lang.Object
A group of time-zone rules wrapping a provider of multiple versions of the data.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
Fields Modifier and Type Field Description private java.lang.String
groupID
The zone rules group ID, such as 'TZDB'.private static java.util.concurrent.ConcurrentMap<java.lang.String,ZoneRulesGroup>
GROUPS
The zone rule groups.private static java.util.Map<java.lang.String,java.lang.Object>
IDS
The zone IDs.private static java.util.regex.Pattern
PATTERN_GROUP
Group ID pattern.private static java.util.regex.Pattern
PATTERN_VERSION
Version ID pattern.private java.util.concurrent.atomic.AtomicReference<java.util.TreeMap<java.lang.String,ZoneRulesVersion>>
versions
The versions and rules.
-
Constructor Summary
Constructors Modifier Constructor Description private
ZoneRulesGroup(java.lang.String groupID)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(java.lang.Object otherGroup)
Is this instance equal to that specified by comparing the group ID.static java.util.List<ZoneRulesGroup>
getAvailableGroups()
Gets the set of available zone rule groups.java.util.Set<java.lang.String>
getAvailableVersionIDs()
Gets the set of available versions for this group.static ZoneRulesGroup
getGroup(java.lang.String groupID)
Gets a group by ID, such as 'TZDB'.java.lang.String
getID()
Gets the ID of the group, such as 'TZDB'.java.lang.String
getLatestVersionID()
Gets the latest available version of the group's data.java.lang.String
getLatestVersionID(java.lang.String regionID)
Gets the latest available version of the group's data for a region.java.lang.String
getLatestVersionIDValidFor(java.lang.String regionID, OffsetDateTime dateTime)
Finds the latest version ID that is valid forstatic java.util.Set<java.lang.String>
getParsableIDs()
Gets a view of the complete set of parsable group:region IDs.java.util.Set<java.lang.String>
getRegionIDs(java.lang.String versionID)
Gets the set of available region IDs for this group that are valid for the specified version.ZoneRules
getRules(java.lang.String regionID, java.lang.String versionID)
Gets the rules for the specified region#version ID combination.ZoneRules
getRulesValidFor(java.lang.String regionID, java.lang.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(java.lang.String groupID)
Checks if the group ID is valid.boolean
isValidRegionID(java.lang.String regionID)
Checks if the region ID is valid.boolean
isValidRules(java.lang.String regionID, java.lang.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.java.lang.String
toString()
Returns a string representation of the group using the group ID.
-
-
-
Field Detail
-
PATTERN_GROUP
private static final java.util.regex.Pattern PATTERN_GROUP
Group ID pattern.
-
PATTERN_VERSION
private static final java.util.regex.Pattern PATTERN_VERSION
Version ID pattern.
-
IDS
private static final java.util.Map<java.lang.String,java.lang.Object> IDS
The zone IDs. Should not be empty.
-
GROUPS
private static final java.util.concurrent.ConcurrentMap<java.lang.String,ZoneRulesGroup> GROUPS
The zone rule groups. Should not be empty.
-
groupID
private final java.lang.String groupID
The zone rules group ID, such as 'TZDB'.
-
versions
private java.util.concurrent.atomic.AtomicReference<java.util.TreeMap<java.lang.String,ZoneRulesVersion>> versions
The versions and rules.
-
-
Constructor Detail
-
ZoneRulesGroup
private ZoneRulesGroup(java.lang.String groupID)
Constructor.- Parameters:
groupID
- the group ID, not null- Throws:
CalendricalException
- if the group ID is invalid
-
-
Method Detail
-
isValidGroupID
public static boolean isValidGroupID(java.lang.String groupID)
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
public static ZoneRulesGroup getGroup(java.lang.String groupID)
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
public static java.util.List<ZoneRulesGroup> 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
public static java.util.Set<java.lang.String> 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
public static ZoneRulesGroup registerProvider(ZoneRulesDataProvider provider)
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
private void registerProvider0(ZoneRulesDataProvider provider)
Registers a zone rules provider with this group.- Parameters:
provider
- the provider to register, not null
-
getID
public java.lang.String getID()
Gets the ID of the group, such as 'TZDB'.- Returns:
- the ID of the group, never null
-
isValidRules
public boolean isValidRules(java.lang.String regionID, java.lang.String versionID)
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
public ZoneRules getRules(java.lang.String regionID, java.lang.String versionID)
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
public ZoneRules getRulesValidFor(java.lang.String regionID, java.lang.String versionID, OffsetDateTime dateTime)
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
public java.lang.String getLatestVersionIDValidFor(java.lang.String regionID, OffsetDateTime dateTime)
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
public java.util.Set<java.lang.String> 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
public java.lang.String 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
public java.lang.String getLatestVersionID(java.lang.String regionID)
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
public boolean isValidRegionID(java.lang.String regionID)
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
public java.util.Set<java.lang.String> getRegionIDs(java.lang.String versionID)
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
public boolean equals(java.lang.Object otherGroup)
Is this instance equal to that specified by comparing the group ID.- Overrides:
equals
in classjava.lang.Object
- Parameters:
otherGroup
- the other group, null returns false- Returns:
- true if this zone is the same as that specified
-
hashCode
public int hashCode()
A hash code for this object.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a suitable hash code
-
toString
public java.lang.String toString()
Returns a string representation of the group using the group ID.- Overrides:
toString
in classjava.lang.Object
- Returns:
- the string representation, never null
-
-