Class 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 for
      static 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.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • 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 invalid
        CalendricalException - 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 false
        versionID - 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 null
        versionID - 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 null
        versionID - the time-zone version ID, empty means floating version, not null
        dateTime - 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 for

        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.

        Parameters:
        regionID - the time-zone region ID, not null
        dateTime - the date-time that must be valid, not null
        Returns:
        the matched zone rules, never null
        Throws:
        CalendricalException - if the region is unknown
        CalendricalException - 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 class java.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 class java.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 class java.lang.Object
        Returns:
        the string representation, never null