javax.time.calendar
Class ZoneId

java.lang.Object
  extended by javax.time.calendar.ZoneId
All Implemented Interfaces:
java.io.Serializable, Calendrical

public abstract class ZoneId
extends java.lang.Object
implements Calendrical, java.io.Serializable

A time-zone id 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.

A simple view considers that this class represents one geographical region with time-zone rules. Viewed like that, this class is a direct replacement for the TimeZone class, such that this class accepts most of the same IDs. However, this class, and supporting classes like ZoneRules provide significantly more power behind the scenes.

Time zones

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, ZoneId 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 a date-time is created and stored using one version of the rules, and then loaded 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.

ZoneId 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.

Author:
Stephen Colebourne
See Also:
Serialized Form

Field Summary
static java.util.Map<java.lang.String,java.lang.String> OLD_IDS_POST_2005
          A map of zone overrides to enable the older US time-zone names to be used.
static java.util.Map<java.lang.String,java.lang.String> OLD_IDS_PRE_2005
          A map of zone overrides to enable the older US time-zone names to be used.
static ZoneId UTC
          The time-zone id for 'UTC'.
 
Method Summary
 boolean equals(java.lang.Object obj)
          Checks if this time-zone ID is equal to another time-zone ID.
static ZoneId from(Calendrical... calendricals)
          Obtains an instance of ZoneId from a set of calendricals.
<T> T
get(CalendricalRule<T> ruleToDerive)
          Gets the value of the specified calendrical rule.
abstract  ZoneRulesGroup getGroup()
          Finds the zone rules group for the stored group ID, such as 'TZDB'.
abstract  java.lang.String getGroupID()
          Gets the time-zone rules group ID, such as TZDB.
abstract  java.lang.String getID()
          Gets the unique time-zone ID.
abstract  java.lang.String getRegionID()
          Gets the time-zone region identifier, such as Europe/London.
abstract  ZoneRules getRules()
          Gets the time-zone rules allowing calculations to be performed.
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.
 java.lang.String getText(TextStyle style, java.util.Locale locale)
          Gets the textual representation of the zone, such as 'British Time'.
abstract  java.lang.String getVersionID()
          Gets the time-zone rules group version, such as '2009b.
 int hashCode()
          A hash code for this time-zone ID.
abstract  boolean isFixed()
          Checks of the time-zone is fixed, such that the offset never varies.
 boolean isFloatingVersion()
          Checks if the version is floating.
abstract  boolean isLatestVersion()
          Checks if the version is the latest version.
abstract  boolean isValid()
          Checks if this time-zone is valid such that rules can be obtained for it.
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.
static ZoneId of(java.lang.String zoneID)
          Obtains an instance of ZoneId from an identifier ensuring that the identifier is valid and available for use.
static ZoneId of(java.lang.String timeZoneIdentifier, java.util.Map<java.lang.String,java.lang.String> aliasMap)
          Obtains an instance of ZoneId using its ID using a map of aliases to supplement the standard zone IDs.
static ZoneId of(ZoneOffset offset)
          Obtains an instance of ZoneId representing a fixed time-zone.
static ZoneId ofUnchecked(java.lang.String zoneID)
          Obtains an instance of ZoneId from an identifier without checking if the time-zone has available rules.
static CalendricalRule<ZoneId> rule()
          Gets the rule for ZoneId.
 java.lang.String toString()
          Outputs this offset as a String, using the ID.
abstract  ZoneId withFloatingVersion()
          Returns a copy of this time-zone with a floating version.
abstract  ZoneId withLatestVersion()
          Returns a copy of this time-zone with the latest available version ID.
abstract  ZoneId withLatestVersionValidFor(OffsetDateTime dateTime)
          Returns a copy of this time-zone with the latest version that is valid for the specified date-time and offset.
abstract  ZoneId withVersion(java.lang.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 Detail

UTC

public static final ZoneId UTC
The time-zone id for 'UTC'. Note that it is intended that fixed offset time-zones like this are rarely used. Applications should use ZoneOffset and OffsetDateTime in preference.


OLD_IDS_PRE_2005

public static final java.util.Map<java.lang.String,java.lang.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:

The map is unmodifiable.


OLD_IDS_POST_2005

public static final java.util.Map<java.lang.String,java.lang.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:

The map is unmodifiable.

Method Detail

rule

public static CalendricalRule<ZoneId> rule()
Gets the rule for ZoneId.

Returns:
the rule for the time-zone, not null

of

public static ZoneId of(java.lang.String timeZoneIdentifier,
                        java.util.Map<java.lang.String,java.lang.String> aliasMap)
Obtains an instance of ZoneId 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, not null
Throws:
CalendricalException - if the time-zone cannot be found

of

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

Six forms of identifier are recognized:

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(CharSequence). 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, not null
Throws:
CalendricalException - if the time-zone cannot be found

ofUnchecked

public static ZoneId ofUnchecked(java.lang.String zoneID)
Obtains an instance of ZoneId 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 ZoneId, 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, not null
Throws:
CalendricalException - if the time-zone cannot be found

of

public static ZoneId of(ZoneOffset offset)
Obtains an instance of ZoneId 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, not null

from

public static ZoneId from(Calendrical... calendricals)
Obtains an instance of ZoneId from a set of calendricals.

A calendrical represents some form of date and time information. This method combines the input calendricals into a time-zone.

Parameters:
calendricals - the calendricals to create a time-zone from, no nulls, not null
Returns:
the time-zone, not null
Throws:
CalendricalException - if unable to merge to a time-zone

get

public <T> T get(CalendricalRule<T> ruleToDerive)
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:
ruleToDerive - the rule to derive, not null
Returns:
the value for the rule, null if the value cannot be returned

getID

public abstract java.lang.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, not null

getGroupID

public abstract java.lang.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, not null

getRegionID

public abstract java.lang.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, not null

getVersionID

public abstract java.lang.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, not 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 ZoneId withFloatingVersion()
Returns a copy of this time-zone with a floating version.

For group based time-zones, this returns a ZoneId 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, not 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 ZoneId 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, not null
Throws:
CalendricalException - if the version is non-floating and the group or region ID is not found

withVersion

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

For group based time-zones, this returns a ZoneId 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, not 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 ZoneId 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, not 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 ZoneId instance even when the rules are not available. This typically occurs when a ZoneId is loaded from a previously stored version but the rules are not available. In this case, the ZoneId 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, not 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, not 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, not null
Throws:
CalendricalException - if the zone ID cannot be found
CalendricalException - if no rules match the zone ID and date-time

getText

public java.lang.String getText(TextStyle style,
                                java.util.Locale locale)
Gets the textual representation of the zone, such as 'British Time'.

This returns a textual description for the time-zone ID.

If no textual mapping is found then the region ID is returned.

Parameters:
locale - the locale to use, not null
Returns:
the short text value of the day-of-week, not null

equals

public boolean equals(java.lang.Object obj)
Checks if this time-zone ID is equal to another time-zone ID.

The comparison is based on the ID.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object to check, null returns false
Returns:
true if this is equal to the other time-zone ID

hashCode

public int hashCode()
A hash code for this time-zone ID.

Overrides:
hashCode in class java.lang.Object
Returns:
a suitable hash code

toString

public java.lang.String toString()
Outputs this offset as a String, using the ID.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of this time-zone ID, not null