Class TimeZone

java.lang.Object
javax.time.calendar.TimeZone
All Implemented Interfaces:
Serializable, Calendrical
Direct Known Subclasses:
TimeZone.Fixed, TimeZone.ID

public abstract class TimeZone extends Object implements Calendrical, Serializable
A time-zone representing the set of rules by which the zone offset varies through the year and historically.

Time zones are geographical regions where the same rules for time apply. The rules are defined by governments and change frequently.

There are a number of sources of time-zone information available, each represented by an instance of ZoneRulesGroup. One group is provided as standard - 'TZDB' - and applications can add more as required.

Each group defines a naming scheme for the regions of the time-zone. The format of the region is specific to the group. For example, the 'TZDB' group typically use the format {area}/{city}, such as 'Europe/London'.

Each group typically produces multiple versions of their data. The format of the version is specific to the group. For example, the 'TZDB' group use the format {year}{letter}, such as '2009b'.

In combination, a unique ID is created expressing the time-zone, formed from {groupID}:{regionID}#{versionID}.

The version can be set to an empty string. This represents the "floating version". The floating version will always choose the latest applicable set of rules. Applications will probably choose to use the floating version, as it guarantees usage of the latest rules.

In addition to the group:region#version combinations, TimeZone can represent a fixed offset. This has an empty group and version ID. It is not possible to have an invalid instance of a fixed time-zone.

The purpose of capturing all this information is to handle issues when manipulating and persisting time-zones. For example, consider what happens if the government of a country changed the start or end of daylight savings time. If you created and stored a date using one version of the rules, and then load it up when a new version of the rules are in force, what should happen? The date might now be invalid, for example due to a gap in the local time-line. By storing the version of the time-zone rules data together with the date, it is possible to tell that the rules have changed and to process accordingly.

TimeZone merely represents the identifier of the zone. The actual rules are provided by ZoneRules. One difference is that serializing this class only stores the reference to the zone, whereas serializing ZoneRules stores the entire set of rules.

After deserialization, or by using the special factory ofUnchecked(java.lang.String), it is possible for the time-zone to represent a group/region/version combination that is unavailable. Since this class can still be loaded even when the rules cannot, the application can continue. For example, a ZonedDateTime instance could still be queried. The application might also take appropriate corrective action. For example, an application might choose to download missing rules from a central server.

TimeZone is immutable and thread-safe.

See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (package private) static final class 
    Fixed time-zone.
    (package private) static final class 
    ID based time-zone.
    (package private) static final class 
    Rule implementation.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Map<String,String>
    A map of zone overrides to enable the older US time-zone names to be used.
    static final Map<String,String>
    A map of zone overrides to enable the older US time-zone names to be used.
    private static final Pattern
    The group:region#version ID pattern.
    private static final long
    A serialization identifier for this class.
    static final TimeZone
    The time-zone offset for UTC, with an id of 'UTC'.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructor only accessible within the package.
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object otherZone)
    Is this instance equal to that specified by comparing the ID.
    <T> T
    Gets the value of the specified calendrical rule.
    Finds the zone rules group for the stored group ID, such as 'TZDB'.
    abstract String
    Gets the time-zone rules group ID, such as 'TZDB'.
    abstract String
    Gets the unique time-zone ID.
    Gets the textual name of this zone.
    abstract String
    Gets the time-zone region identifier, such as 'Europe/London'.
    abstract ZoneRules
    Gets the time-zone rules allowing calculations to be performed.
    abstract ZoneRules
    Gets the time-zone rules allowing calculations to be performed, ensuring that the date-time and offset specified is valid for the returned rules.
    Gets the short textual name of this zone.
    abstract String
    Gets the time-zone rules group version, such as '2009b'.
    int
    A hash code for this time-zone ID.
    abstract boolean
    Checks of the time-zone is fixed, such that the offset never varies.
    boolean
    Checks if the version is floating.
    abstract boolean
    Checks if the version is the latest version.
    abstract boolean
    Checks if this time-zone is valid such that rules can be obtained for it.
    abstract boolean
    Checks if this time-zone is valid such that rules can be obtained for it which are valid for the specified date-time and offset.
    static TimeZone
    of(String zoneID)
    Obtains an instance of TimeZone from an identifier ensuring that the identifier is valid and available for use.
    static TimeZone
    of(String timeZoneIdentifier, Map<String,String> aliasMap)
    Obtains an instance of TimeZone using its ID using a map of aliases to supplement the standard zone IDs.
    static TimeZone
    of(ZoneOffset offset)
    Obtains an instance of TimeZone representing a fixed time-zone.
    private static TimeZone
    ofID(String zoneID, boolean checkAvailable)
    Obtains an instance of TimeZone from an identifier.
    static TimeZone
    Obtains an instance of TimeZone from an identifier without checking if the time-zone has available rules.
    Gets the rule for TimeZone.
    Returns a string representation of the time-zone.
    abstract TimeZone
    Returns a copy of this time-zone with a floating version.
    abstract TimeZone
    Returns a copy of this time-zone with the latest available version ID.
    abstract TimeZone
    Returns a copy of this time-zone with the latest version that is valid for the specified date-time and offset.
    abstract TimeZone
    withVersion(String versionID)
    Returns a copy of this time-zone with the specified version ID.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • PATTERN

      private static final Pattern PATTERN
      The group:region#version ID pattern.
    • serialVersionUID

      private static final long serialVersionUID
      A serialization identifier for this class.
      See Also:
    • UTC

      public static final TimeZone UTC
      The time-zone offset for UTC, with an id of 'UTC'.
    • OLD_IDS_PRE_2005

      public static final Map<String,String> OLD_IDS_PRE_2005
      A map of zone overrides to enable the older US time-zone names to be used.

      This maps as follows:

      • EST - America/Indianapolis
      • MST - America/Phoenix
      • HST - Pacific/Honolulu
      • ACT - Australia/Darwin
      • AET - Australia/Sydney
      • AGT - America/Argentina/Buenos_Aires
      • ART - Africa/Cairo
      • AST - America/Anchorage
      • BET - America/Sao_Paulo
      • BST - Asia/Dhaka
      • CAT - Africa/Harare
      • CNT - America/St_Johns
      • CST - America/Chicago
      • CTT - Asia/Shanghai
      • EAT - Africa/Addis_Ababa
      • ECT - Europe/Paris
      • IET - America/Indiana/Indianapolis
      • IST - Asia/Kolkata
      • JST - Asia/Tokyo
      • MIT - Pacific/Apia
      • NET - Asia/Yerevan
      • NST - Pacific/Auckland
      • PLT - Asia/Karachi
      • PNT - America/Phoenix
      • PRT - America/Puerto_Rico
      • PST - America/Los_Angeles
      • SST - Pacific/Guadalcanal
      • VST - Asia/Ho_Chi_Minh
      The map is unmodifiable.
    • OLD_IDS_POST_2005

      public static final Map<String,String> OLD_IDS_POST_2005
      A map of zone overrides to enable the older US time-zone names to be used.

      This maps as follows:

      • EST - UTC-05:00
      • HST - UTC-10:00
      • MST - UTC-07:00
      • ACT - Australia/Darwin
      • AET - Australia/Sydney
      • AGT - America/Argentina/Buenos_Aires
      • ART - Africa/Cairo
      • AST - America/Anchorage
      • BET - America/Sao_Paulo
      • BST - Asia/Dhaka
      • CAT - Africa/Harare
      • CNT - America/St_Johns
      • CST - America/Chicago
      • CTT - Asia/Shanghai
      • EAT - Africa/Addis_Ababa
      • ECT - Europe/Paris
      • IET - America/Indiana/Indianapolis
      • IST - Asia/Kolkata
      • JST - Asia/Tokyo
      • MIT - Pacific/Apia
      • NET - Asia/Yerevan
      • NST - Pacific/Auckland
      • PLT - Asia/Karachi
      • PNT - America/Phoenix
      • PRT - America/Puerto_Rico
      • PST - America/Los_Angeles
      • SST - Pacific/Guadalcanal
      • VST - Asia/Ho_Chi_Minh
      The map is unmodifiable.
  • Constructor Details

    • TimeZone

      TimeZone()
      Constructor only accessible within the package.
  • Method Details

    • of

      public static TimeZone of(String timeZoneIdentifier, Map<String,String> aliasMap)
      Obtains an instance of TimeZone using its ID using a map of aliases to supplement the standard zone IDs.

      Many users of time-zones use short abbreviations, such as PST for 'Pacific Standard Time' and PDT for 'Pacific Daylight Time'. These abbreviations are not unique, and so cannot be used as identifiers. This method allows a map of string to time-zone to be setup and reused within an application.

      Parameters:
      timeZoneIdentifier - the time-zone id, not null
      aliasMap - a map of time-zone IDs (typically abbreviations) to real time-zone IDs, not null
      Returns:
      the time-zone, never null
      Throws:
      IllegalArgumentException - if the time-zone cannot be found
    • of

      public static TimeZone of(String zoneID)
      Obtains an instance of TimeZone from an identifier ensuring that the identifier is valid and available for use.

      Six forms of identifier are recognized:

      • {groupID}:{regionID}#{versionID} - full
      • {groupID}:{regionID} - implies the floating version
      • {regionID}#{versionID} - implies 'TZDB' group and specific version
      • {regionID} - implies 'TZDB' group and the floating version
      • UTC{offset} - fixed time-zone
      • GMT{offset} - fixed time-zone
      Group IDs must match regular expression [A-Za-z0-9._-]+.
      Region IDs must match regular expression [A-Za-z0-9%@~/+._-]+.
      Version IDs must match regular expression [A-Za-z0-9._-]+.

      Most of the formats are based around the group, version and region IDs. The version and region ID formats are specific to the group.

      The default group is 'TZDB' which has versions of the form {year}{letter}, such as '2009b'. The region ID for the 'TZDB' group is generally of the form '{area}/{city}', such as 'Europe/Paris'. This is compatible with most IDs from TimeZone.

      For example, if a provider is loaded with the ID 'MyProvider' containing a zone ID of 'France', then the unique key for version 2.1 would be 'MyProvider:France#2.1'. A specific version of the TZDB provider is 'TZDB:Asia/Tokyo#2008g'.

      Once parsed, this factory will ensure that the group, region and version combination is valid and rules can be obtained.

      The alternate format is for fixed time-zones, where the offset never changes over time. A fixed time-zone is returned if the first three characters are 'UTC' or 'GMT' and the remainder of the ID is a valid format for ZoneOffset.of(String). The result will have a normalized time-zone ID of 'UTC{offset}', or just 'UTC' if the offset is zero.

      Note that it is intended that fixed offset time-zones are rarely used. Applications should use ZoneOffset and OffsetDateTime in preference.

      Parameters:
      zoneID - the time-zone identifier, not null
      Returns:
      the time-zone, never null
      Throws:
      CalendricalException - if the time-zone cannot be found
    • ofUnchecked

      public static TimeZone ofUnchecked(String zoneID)
      Obtains an instance of TimeZone from an identifier without checking if the time-zone has available rules.

      The identifier is parsed in a similar manner to of(String). However, there is no check to ensure that the group, region and version resolve to a set of rules that can be loaded. This factory does however check that the identifier meets the acceptable format.

      This method is intended for advanced use cases. One example might be a system that always retrieves time-zone rules from a remote server. Using this factory allows a TimeZone, and thus a ZonedDateTime, to be created without loading the rules from the remote server.

      Parameters:
      zoneID - the time-zone identifier, not null
      Returns:
      the time-zone, never null
      Throws:
      CalendricalException - if the time-zone cannot be found
    • ofID

      private static TimeZone ofID(String zoneID, boolean checkAvailable)
      Obtains an instance of TimeZone from an identifier.
      Parameters:
      zoneID - the time-zone identifier, not null
      checkAvailable - whether to check if the time-zone ID is available
      Returns:
      the time-zone, never null
      Throws:
      CalendricalException - if the time-zone cannot be found
    • of

      public static TimeZone of(ZoneOffset offset)
      Obtains an instance of TimeZone representing a fixed time-zone.

      The time-zone returned from this factory has a fixed offset for all time. The region ID will return an identifier formed from 'UTC' and the offset. The group and version IDs will both return an empty string.

      Fixed time-zones are always valid.

      Parameters:
      offset - the zone offset to create a fixed zone for, not null
      Returns:
      the time-zone for the offset, never null
    • getID

      public abstract String getID()
      Gets the unique time-zone ID.

      The unique key is created from the group ID, version ID and region ID. The format is {groupID}:{regionID}#{versionID}. If the group is 'TZDB' then the {groupID}: is omitted. If the version is floating, then the #{versionID} is omitted. Fixed time-zones will only output the region ID.

      Returns:
      the time-zone unique ID, never null
    • getGroupID

      public abstract String getGroupID()
      Gets the time-zone rules group ID, such as 'TZDB'.

      The group ID is the first part of the full unique ID. Time zone rule data is supplied by a group, typically a company or organization. The default group is 'TZDB' representing the public time-zone database.

      For fixed time-zones, the group ID will be an empty string.

      Returns:
      the time-zone rules group ID, never null
    • getRegionID

      public abstract String getRegionID()
      Gets the time-zone region identifier, such as 'Europe/London'.

      The region ID is the second part of the full unique ID. Time zone rules are defined for a region and this element represents that region. The ID uses a format specific to the group. The default 'TZDB' group generally uses the format {area}/{city}, such as 'Europe/Paris'.

      Returns:
      the time-zone rules region ID, never null
    • getVersionID

      public abstract String getVersionID()
      Gets the time-zone rules group version, such as '2009b'.

      The version ID is the third part of the full unique ID. Time zone rules change over time as governments change the associated laws. The time-zone groups capture these changes by issuing multiple versions of the data. An application can reference the exact set of rules used by using the group ID and version. Once loaded, there is no way to unload a version of the rules, however new versions may be added.

      The version can be an empty string which represents the floating version. This always uses the latest version of the rules available.

      For fixed time-zones, the version ID will be an empty string.

      Returns:
      the time-zone rules version ID, empty if the version is floating, never null
    • isFixed

      public abstract boolean isFixed()
      Checks of the time-zone is fixed, such that the offset never varies.

      It is intended that OffsetDateTime, OffsetDate and OffsetTime are used in preference to fixed offset time-zones in ZonedDateTime.

      Returns:
      true if the time-zone is fixed and the offset never changes
    • isFloatingVersion

      public boolean isFloatingVersion()
      Checks if the version is floating.

      A floating version will track the latest available version of the rules.

      For group based time-zones, this returns true if the version ID is empty, which is the definition of a floating zone.

      For fixed time-zones, true is returned as the data is always the latest.

      Returns:
      true if the version is floating
    • withFloatingVersion

      public abstract TimeZone withFloatingVersion()
      Returns a copy of this time-zone with a floating version.

      For group based time-zones, this returns a TimeZone with the same group and region, but a floating version. The group and region IDs are not validated.

      For fixed time-zones, this is returned.

      Returns:
      the new updated time-zone, never null
      Throws:
      CalendricalException - if the time-zone is fixed
    • isLatestVersion

      public abstract boolean isLatestVersion()
      Checks if the version is the latest version.

      For floating group based time-zones, true is returned.

      For non-floating group based time-zones, this returns true if the version stored is the same as the latest version available for the group and region. The group and region IDs are validated in order to calculate the latest version.

      For fixed time-zones, true is returned.

      Returns:
      true if the version is the latest available
      Throws:
      CalendricalException - if the version is non-floating and the group or region ID is not found
    • withLatestVersion

      public abstract TimeZone withLatestVersion()
      Returns a copy of this time-zone with the latest available version ID.

      For floating and non-floating group based time-zones, this returns a zone with the same group and region, but the latest version that has been registered. The group and region IDs are validated in order to calculate the latest version.

      For fixed time-zones, this is returned.

      Returns:
      the new updated time-zone, never null
      Throws:
      CalendricalException - if the version is non-floating and the group or region ID is not found
    • withVersion

      public abstract TimeZone withVersion(String versionID)
      Returns a copy of this time-zone with the specified version ID.

      For group based time-zones, this returns a TimeZone with the same group and region, but the specified version. The group and region IDs are validated to ensure that the version is valid.

      For fixed time-zones, the version must be an empty string, otherwise an exception is thrown.

      Parameters:
      versionID - the version ID to use, empty means floating version, not null
      Returns:
      the new updated time-zone, never null
      Throws:
      CalendricalException - if the time-zone is fixed and the version is not empty
      CalendricalException - if the group, region or version ID is not found
    • withLatestVersionValidFor

      public abstract TimeZone withLatestVersionValidFor(OffsetDateTime dateTime)
      Returns a copy of this time-zone with the latest version that is valid for the specified date-time and offset.

      This will search for a version of the time-zone rules that would make the specified date-time valid. This is needed for cases where the time-zone changes and you hold a reference to a date-time created before the rules changed.

      This method validates the group and region IDs.

      Parameters:
      dateTime - the date-time to get the latest version for
      Returns:
      the new updated time-zone, never null
      Throws:
      CalendricalException - if the group or region ID is not found
      CalendricalException - if there are no valid rules for the date-time
    • getGroup

      public abstract ZoneRulesGroup getGroup()
      Finds the zone rules group for the stored group ID, such as 'TZDB'.

      Time zone rules are provided by groups referenced by an ID.

      Fixed time-zones are not provided by a group, thus this method throws an exception if the time-zone is fixed.

      Callers of this method need to be aware of an unusual scenario. It is possible to obtain a TimeZone instance even when the rules are not available. This typically occurs when a TimeZone is loaded from a previously stored version but the rules are not available. In this case, the TimeZone instance is still valid, as is any associated object, such as ZonedDateTime. It is impossible to perform any calculations that require the rules however, and this method will throw an exception.

      Returns:
      the time-zone rules group ID, never null
      Throws:
      CalendricalException - if the time-zone is fixed
      CalendricalException - if the group ID cannot be found
    • isValid

      public abstract boolean isValid()
      Checks if this time-zone is valid such that rules can be obtained for it.

      This will return true if the rules are available for the group, region and version ID combination. If this method returns true, then getRules() will return a valid rules instance.

      A time-zone can be invalid if it is deserialized in a JVM which does not have the same rules loaded as the JVM that stored it.

      If this object declares a floating version of the rules and a background thread is used to update the available rules, then the result of calling this method may vary over time. Each individual call will be still remain thread-safe.

      If this is a fixed time-zone, then it is always valid.

      Returns:
      true if this time-zone is valid and rules are available
    • getRules

      public abstract ZoneRules getRules()
      Gets the time-zone rules allowing calculations to be performed.

      The rules provide the functionality associated with a time-zone, such as finding the offset for a given instant or local date-time. Different rules may be returned depending on the group, version and zone.

      If this object declares a specific version of the rules, then the result will be of that version. If this object declares a floating version of the rules, then the latest version available will be returned.

      A time-zone can be invalid if it is deserialized in a JVM which does not have the same rules loaded as the JVM that stored it. In this case, calling this method will throw an exception.

      If this object declares a floating version of the rules and a background thread is used to update the available rules, then the result of calling this method may vary over time. Each individual call will be still remain thread-safe.

      Returns:
      the rules, never null
      Throws:
      CalendricalException - if the group, region or version ID cannot be found
    • isValidFor

      public abstract boolean isValidFor(OffsetDateTime dateTime)
      Checks if this time-zone is valid such that rules can be obtained for it which are valid for the specified date-time and offset.

      This will return true if the rules are available for the group, region and version ID combination that are valid for the specified date-time. If this method returns true, then getRulesValidFor(OffsetDateTime) will return a valid rules instance.

      A time-zone can be invalid if it is deserialized in a JVM which does not have the same rules loaded as the JVM that stored it.

      If this object declares a floating version of the rules and a background thread is used to update the available rules, then the result of calling this method may vary over time. Each individual call will be still remain thread-safe.

      If this is a fixed time-zone, then it is valid if the offset matches the date-time.

      Parameters:
      dateTime - a date-time for which the rules must be valid, null returns false
      Returns:
      true if this time-zone is valid and rules are available
    • getRulesValidFor

      public abstract ZoneRules getRulesValidFor(OffsetDateTime dateTime)
      Gets the time-zone rules allowing calculations to be performed, ensuring that the date-time and offset specified is valid for the returned rules.

      The rules provide the functionality associated with a time-zone, such as finding the offset for a given instant or local date-time. Different rules may be returned depending on the group, version and zone.

      If this object declares a specific version of the rules, then the result will be of that version providing that the specified date-time is valid for those rules. If this object declares a floating version of the rules, then the latest version of the rules where the date-time is valid will be returned.

      A time-zone can be invalid if it is deserialized in a JVM which does not have the same rules loaded as the JVM that stored it. In this case, calling this method will throw an exception.

      If this object declares a floating version of the rules and a background thread is used to update the available rules, then the result of calling this method may vary over time. Each individual call will be still remain thread-safe.

      Parameters:
      dateTime - a date-time for which the rules must be valid, not null
      Returns:
      the latest rules for this zone where the date-time is valid, never null
      Throws:
      CalendricalException - if the zone ID cannot be found
      CalendricalException - if no rules match the zone ID and date-time
    • getName

      public String getName()
      Gets the textual name of this zone.
      Returns:
      the time-zone name, never null
    • getShortName

      public String getShortName()
      Gets the short textual name of this zone.
      Returns:
      the time-zone short name, never null
    • equals

      public boolean equals(Object otherZone)
      Is this instance equal to that specified by comparing the ID.
      Overrides:
      equals in class Object
      Parameters:
      otherZone - the other zone, null returns false
      Returns:
      true if this zone is the same as that specified
    • hashCode

      public int hashCode()
      A hash code for this time-zone ID.
      Overrides:
      hashCode in class Object
      Returns:
      a suitable hash code
    • toString

      public String toString()
      Returns a string representation of the time-zone.

      This returns getID().

      Overrides:
      toString in class Object
      Returns:
      the time-zone ID, never null
    • get

      public <T> T get(CalendricalRule<T> rule)
      Gets the value of the specified calendrical rule.

      This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this offset then null will be returned.

      Specified by:
      get in interface Calendrical
      Parameters:
      rule - the rule to use, not null
      Returns:
      the value for the rule, null if the value cannot be returned
    • rule

      public static CalendricalRule<TimeZone> rule()
      Gets the rule for TimeZone.
      Returns:
      the rule for the time-zone, never null