Class TimeZone
- java.lang.Object
-
- javax.time.calendar.TimeZone
-
- All Implemented Interfaces:
Serializable
,Calendrical
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 byZoneRules
. One difference is that serializing this class only stores the reference to the zone, whereas serializingZoneRules
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, aZonedDateTime
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
Fields Modifier and Type Field Description static Map<String,String>
OLD_IDS_POST_2005
A map of zone overrides to enable the older US time-zone names to be used.static Map<String,String>
OLD_IDS_PRE_2005
A map of zone overrides to enable the older US time-zone names to be used.static TimeZone
UTC
The time-zone offset for UTC, with an id of 'UTC'.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description boolean
equals(Object otherZone)
Is this instance equal to that specified by comparing the ID.<T> T
get(CalendricalRule<T> rule)
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 String
getGroupID()
Gets the time-zone rules group ID, such as 'TZDB'.abstract String
getID()
Gets the unique time-zone ID.String
getName()
Gets the textual name of this zone.abstract 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.String
getShortName()
Gets the short textual name of this zone.abstract 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 TimeZone
of(String zoneID)
Obtains an instance ofTimeZone
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 ofTimeZone
using its ID using a map of aliases to supplement the standard zone IDs.static TimeZone
of(ZoneOffset offset)
Obtains an instance ofTimeZone
representing a fixed time-zone.static TimeZone
ofUnchecked(String zoneID)
Obtains an instance ofTimeZone
from an identifier without checking if the time-zone has available rules.static CalendricalRule<TimeZone>
rule()
Gets the rule forTimeZone
.String
toString()
Returns a string representation of the time-zone.abstract TimeZone
withFloatingVersion()
Returns a copy of this time-zone with a floating version.abstract TimeZone
withLatestVersion()
Returns a copy of this time-zone with the latest available version ID.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.abstract TimeZone
withVersion(String versionID)
Returns a copy of this time-zone with the specified version ID.
-
-
-
Field Detail
-
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
-
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
-
-
Method Detail
-
of
public static TimeZone of(String timeZoneIdentifier, Map<String,String> aliasMap)
Obtains an instance ofTimeZone
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 nullaliasMap
- 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 ofTimeZone
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 versionUTC{offset}
- fixed time-zoneGMT{offset}
- fixed time-zone
[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
andOffsetDateTime
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 ofTimeZone
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 aZonedDateTime
, 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
-
of
public static TimeZone of(ZoneOffset offset)
Obtains an instance ofTimeZone
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
andOffsetTime
are used in preference to fixed offset time-zones inZonedDateTime
.- 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 emptyCalendricalException
- 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 foundCalendricalException
- 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 aTimeZone
is loaded from a previously stored version but the rules are not available. In this case, theTimeZone
instance is still valid, as is any associated object, such asZonedDateTime
. 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 fixedCalendricalException
- 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 foundCalendricalException
- 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.
-
hashCode
public int hashCode()
A hash code for this time-zone ID.
-
toString
public String toString()
Returns a string representation of the time-zone.This returns
getID()
.
-
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 interfaceCalendrical
- 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 forTimeZone
.- Returns:
- the rule for the time-zone, never null
-
-