Class TimeZone
- All Implemented Interfaces:
Serializable
,Calendrical
- Direct Known Subclasses:
TimeZone.Fixed
,TimeZone.ID
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 ClassesModifier and TypeClassDescription(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
FieldsModifier and TypeFieldDescriptionA map of zone overrides to enable the older US time-zone names to be used.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 -
Method Summary
Modifier and TypeMethodDescriptionboolean
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
Gets the time-zone rules group ID, such as 'TZDB'.abstract String
getID()
Gets the unique time-zone ID.getName()
Gets the textual name of this zone.abstract String
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.Gets the short textual name of this zone.abstract String
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
Checks if the version is floating.abstract boolean
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
Obtains an instance ofTimeZone
from an identifier ensuring that the identifier is valid and available for use.static TimeZone
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.private static TimeZone
Obtains an instance ofTimeZone
from an identifier.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
.toString()
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
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 Details
-
PATTERN
The group:region#version ID pattern. -
serialVersionUID
private static final long serialVersionUIDA serialization identifier for this class.- See Also:
-
UTC
The time-zone offset for UTC, with an id of 'UTC'. -
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
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
-
-
Constructor Details
-
TimeZone
TimeZone()Constructor only accessible within the package.
-
-
Method Details
-
of
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
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
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
-
ofID
Obtains an instance ofTimeZone
from an identifier.- Parameters:
zoneID
- the time-zone identifier, not nullcheckAvailable
- 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
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
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
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
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
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
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
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
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
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
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
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
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
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
Gets the textual name of this zone.- Returns:
- the time-zone name, never null
-
getShortName
Gets the short textual name of this zone.- Returns:
- the time-zone short name, never null
-
equals
Is this instance equal to that specified by comparing the ID. -
hashCode
public int hashCode()A hash code for this time-zone ID. -
toString
Returns a string representation of the time-zone.This returns
getID()
. -
get
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
Gets the rule forTimeZone
.- Returns:
- the rule for the time-zone, never null
-