public abstract class ZoneId extends Object implements Serializable
Time-zones are geographical regions where the same rules for time apply. The rules are defined by governments and change frequently. This class provides an identifier that locates a single set of rules.
The rule data is split across two main classes:
ZoneId, which only represents the identifier of the rule-set
ZoneRules, which defines the set of rules themselves
One benefit of this separation occurs in serialization. Storing this class will
only store the reference to the zone, whereas serializing ZoneRules will
store the entire set of rules.
Similarly, comparing two ZoneId instances will only compare the identifier,
whereas comparing two ZoneRules instances will actually check to see if the
rules represent the same set of data.
After deserialization, or by using the special factory ofUnchecked(java.lang.String), it is
possible for the ZoneId to represent an identifier that has no available rules.
This approach allows the application to continue and some operations to be performed.
It also allows an application to dynamically download missing rules from a central
server, if desired.
{groupID}:{regionID}.
The group represents the source of time-zone information. This is necessary as multiple companies and organizations provide time-zone data. Two groups are provided as standard, 'TZDB' and 'UTC'.
The 'TZDB' group represents the main public time-zone database.
It typically uses region identifiers of the form {area}/{city},
such as Europe/London. The 'TZDB' group is considered to be the
default such that normally only the region ID is seen in identifiers.
The 'UTC' group represents fixed offsets from UTC/Greenwich.
That concept is best represented using ZoneOffset directly, but a fixed
offset is also a valid ZoneId, hence the 'UTC' group.
The region identifier for the 'UTC' group is the ZoneOffset identifier.
| Modifier and Type | Field and Description |
|---|---|
static String |
GROUP_TZDB
The time-zone group id for 'TZDB'.
|
static String |
GROUP_UTC
The time-zone group id for 'UTC'.
|
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 ZoneId |
UTC
The time-zone id for 'UTC'.
|
| Modifier and Type | Method and Description |
|---|---|
boolean |
equals(Object obj)
Checks if this time-zone ID is equal to another time-zone ID.
|
static ZoneId |
from(DateTimeAccessor dateTime)
Obtains an instance of
ZoneId from a date-time object. |
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.
|
abstract String |
getRegionID()
Gets the time-zone region identifier, such as 'Europe/London'.
|
abstract ZoneRules |
getRules()
Gets the time-zone rules for this ID 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 |
getText(TextStyle style,
Locale locale)
Gets the textual representation of the zone, such as 'British Time'.
|
int |
hashCode()
A hash code for this time-zone ID.
|
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(String zoneID)
Obtains an instance of
ZoneId from an identifier ensuring that the
identifier is valid and available for use. |
static ZoneId |
of(String timeZoneIdentifier,
Map<String,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(String zoneID)
Obtains an instance of
ZoneId from an identifier without checking
if the time-zone has available rules. |
static ZoneId |
systemDefault()
Gets the system default time-zone.
|
String |
toString()
Outputs this zone as a
String, using the ID. |
public static final ZoneId UTC
ZoneOffset and OffsetDateTime in preference.public static final String GROUP_TZDB
The 'TZDB' group represents the main public time-zone database.
public static final String GROUP_UTC
The 'UTC' group represents fixed offsets from UTC/Greenwich, which should
normally be used directly via ZoneOffset.
public static final Map<String,String> OLD_IDS_PRE_2005
This maps as follows:
public static final Map<String,String> OLD_IDS_POST_2005
This maps as follows:
public static ZoneId systemDefault()
This queries TimeZone.getDefault() to find the default time-zone
and converts it to a ZoneId. If the system default time-zone is changed,
then the result of this method will also change.
DateTimeException - if a zone ID cannot be created from the TimeZone objectpublic static ZoneId of(String timeZoneIdentifier, Map<String,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 alias zone IDs (typically abbreviations) to real zone IDs, not nullDateTimeException - if the zone ID cannot be foundpublic static ZoneId of(String zoneID)
ZoneId from an identifier ensuring that the
identifier is valid and available for use.
This method parses the ID, applies any appropriate normalization, and validates it against the known set of IDs for which rules are available.
Four forms of identifier are recognized:
{groupID}:{regionID} - full
{regionID} - implies 'TZDB' group and specific version
UTC{offset} - implies 'UTC' group with fixed offset
GMT{offset} - implies 'UTC' group with fixed offset
[A-Za-z0-9._-]+.[A-Za-z0-9%@~/+._-]+, except
if the group ID is 'UTC' when the regular expression is [Z0-9+:-]+.
The detailed format of the region ID depends on the group.
The default group is 'TZDB' which has region IDs generally of the form '{area}/{city}',
such as 'Europe/Paris' or 'America/New_York'.
This is compatible with most IDs from TimeZone.
For example, the ID in use in Tokyo, Japan is 'Asia/Tokyo'. Passing either 'Asia/Tokyo' or 'TZDB:Asia/Tokyo' will create a valid object for that city.
The three additional special cases can match where the group ID is not specified. If the input starts with UTC or GMT then the remainder is parsed to find an offset and the group ID is treated as 'UTC'. Otherwise, the group ID is considered to be 'TZDB'.
zoneID - the time-zone identifier, not nullDateTimeException - if the zone ID cannot be foundpublic static ZoneId ofUnchecked(String zoneID)
ZoneId from an identifier without checking
if the time-zone has available rules.
This method parses the ID and applies any appropriate normalization.
Unlike of(String), it does not validates the ID against the known set of IDs
for which rules are available.
This method is intended for advanced use cases.
For example, consider a system that always retrieves time-zone rules from a remote server.
Using this factory would allow a ZoneId, and thus a ZonedDateTime,
to be created without loading the rules from the remote server.
zoneID - the time-zone identifier, not nullDateTimeException - if the zone ID 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 group identifier is 'UTC' and the region is the identifier of
the ZoneOffset.
offset - the zone offset to create a fixed zone for, not nullpublic static ZoneId from(DateTimeAccessor dateTime)
ZoneId from a date-time object.
A DateTimeAccessor represents some form of date and time information.
This factory converts the arbitrary date-time object to an instance of ZoneId.
dateTime - the date-time object to convert, not nullDateTimeException - if unable to convert to a ZoneIdpublic abstract String getID()
The unique key is created from the group ID and region ID.
The format is {groupID}:{regionID}.
If the group is 'TZDB' then only the region identifier is returned.
public abstract String getGroupID()
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.
public abstract String getRegionID()
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 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.
DateTimeException - if the time-zone is fixedDateTimeException - if the group ID cannot be foundpublic abstract boolean isValid()
This will return true if the rules are available for this ID. 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 available as the JVM that stored it.
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.
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 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.
DateTimeException - if no rules are available for this IDpublic abstract boolean isValidFor(OffsetDateTime dateTime)
This will return true if the rules declare that the specified date-time is valid.
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 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 falsepublic 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.
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.
dateTime - a date-time for which the rules must be valid, not nullDateTimeException - if the zone ID cannot be foundDateTimeException - if no rules match the zone ID and date-timepublic String getText(TextStyle style, Locale locale)
This returns a textual description for the time-zone ID.
If no textual mapping is found then the full ID is returned.
locale - the locale to use, not nullpublic boolean equals(Object obj)
The comparison is based on the ID.
public int hashCode()