Class ZoneRulesGroup

java.lang.Object
javax.time.calendar.zone.ZoneRulesGroup

public final class ZoneRulesGroup extends 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 Details

  • Constructor Details

    • ZoneRulesGroup

      private ZoneRulesGroup(String groupID)
      Constructor.
      Parameters:
      groupID - the group ID, not null
      Throws:
      CalendricalException - if the group ID is invalid
  • Method Details

    • isValidGroupID

      public static boolean isValidGroupID(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(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 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 Set<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 String getID()
      Gets the ID of the group, such as 'TZDB'.
      Returns:
      the ID of the group, never null
    • isValidRules

      public boolean isValidRules(String regionID, 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(String regionID, 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(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.

      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 String getLatestVersionIDValidFor(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 Set<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 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 String getLatestVersionID(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(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 Set<String> getRegionIDs(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(Object otherGroup)
      Is this instance equal to that specified by comparing the group ID.
      Overrides:
      equals in class 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 Object
      Returns:
      a suitable hash code
    • toString

      public String toString()
      Returns a string representation of the group using the group ID.
      Overrides:
      toString in class Object
      Returns:
      the string representation, never null