|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.time.calendar.ZoneId
public abstract class ZoneId
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.
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.
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. |
|
|
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 |
---|
public static final ZoneId UTC
ZoneOffset
and OffsetDateTime
in preference.
public static final java.util.Map<java.lang.String,java.lang.String> OLD_IDS_PRE_2005
This maps as follows:
public static final java.util.Map<java.lang.String,java.lang.String> OLD_IDS_POST_2005
This maps as follows:
Method Detail |
---|
public static CalendricalRule<ZoneId> rule()
ZoneId
.
public static ZoneId of(java.lang.String timeZoneIdentifier, java.util.Map<java.lang.String,java.lang.String> aliasMap)
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.
timeZoneIdentifier
- the time-zone id, not nullaliasMap
- a map of time-zone IDs (typically abbreviations) to real time-zone IDs, not null
CalendricalException
- if the time-zone cannot be foundpublic static ZoneId of(java.lang.String zoneID)
ZoneId
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
[A-Za-z0-9._-]+
.[A-Za-z0-9%@~/+._-]+
.[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.
zoneID
- the time-zone identifier, not null
CalendricalException
- if the time-zone cannot be foundpublic static ZoneId ofUnchecked(java.lang.String zoneID)
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.
zoneID
- the time-zone identifier, not null
CalendricalException
- if the time-zone cannot be foundpublic static ZoneId of(ZoneOffset offset)
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
.
offset
- the zone offset to create a fixed zone for, not null
public static ZoneId from(Calendrical... calendricals)
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.
calendricals
- the calendricals to create a time-zone from, no nulls, not null
CalendricalException
- if unable to merge to a time-zonepublic <T> T get(CalendricalRule<T> ruleToDerive)
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.
get
in interface Calendrical
ruleToDerive
- the rule to derive, not null
public abstract java.lang.String getID()
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.
public abstract java.lang.String getGroupID()
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.
public abstract java.lang.String getRegionID()
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'.
public abstract java.lang.String getVersionID()
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.
public abstract boolean isFixed()
It is intended that OffsetDateTime
, OffsetDate
and
OffsetTime
are used in preference to fixed offset time-zones
in ZonedDateTime
.
public boolean isFloatingVersion()
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.
public abstract ZoneId withFloatingVersion()
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.
CalendricalException
- if the time-zone is fixedpublic abstract boolean isLatestVersion()
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.
CalendricalException
- if the version is non-floating and the group or region ID is not foundpublic abstract ZoneId withLatestVersion()
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.
CalendricalException
- if the version is non-floating and the group or region ID is not foundpublic abstract ZoneId withVersion(java.lang.String versionID)
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.
versionID
- the version ID to use, empty means floating version, not null
CalendricalException
- if the time-zone is fixed and the version is not empty
CalendricalException
- if the group, region or version ID is not foundpublic abstract ZoneId withLatestVersionValidFor(OffsetDateTime dateTime)
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.
dateTime
- the date-time to get the latest version for
CalendricalException
- if the group or region ID is not found
CalendricalException
- if there are no valid rules for the date-timepublic abstract ZoneRulesGroup getGroup()
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.
CalendricalException
- if the time-zone is fixed
CalendricalException
- if the group ID cannot be foundpublic abstract boolean isValid()
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.
public abstract ZoneRules getRules()
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.
CalendricalException
- if the group, region or version ID cannot be foundpublic abstract boolean isValidFor(OffsetDateTime dateTime)
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.
dateTime
- a date-time for which the rules must be valid, null returns false
public abstract ZoneRules getRulesValidFor(OffsetDateTime dateTime)
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.
dateTime
- a date-time for which the rules must be valid, not null
CalendricalException
- if the zone ID cannot be found
CalendricalException
- if no rules match the zone ID and date-timepublic java.lang.String getText(TextStyle style, java.util.Locale locale)
This returns a textual description for the time-zone ID.
If no textual mapping is found then the region ID
is returned.
locale
- the locale to use, not null
public boolean equals(java.lang.Object obj)
The comparison is based on the ID.
equals
in class java.lang.Object
obj
- the object to check, null returns false
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
String
, using the ID.
toString
in class java.lang.Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |