* A {@code ZoneId} is used to identify the rules used to convert between * an {@link Instant} and a {@link LocalDateTime}. * There are two distinct types of ID: *
* The actual rules, describing when and how the offset changes, are defined by {@link ZoneRules}. * This class is simply an ID used to obtain the underlying rules. * This approach is taken because rules are defined by governments and change * frequently, whereas the ID is stable. *
* The distinction has other effects. Serializing the {@code ZoneId} will only send * the ID, whereas serializing the rules sends the entire data set. * Similarly, a comparison of two IDs only examines the ID, whereas * a comparison of two rules examines the entire data set. * *
* The simplest type of ID is that from {@code ZoneOffset}. * This consists of 'Z' and IDs starting with '+' or '-'. *
* The next type of ID are offset-style IDs with some form of prefix, * such as 'GMT+2' or 'UTC+01:00'. * The recognised prefixes are 'UTC', 'GMT' and 'UT'. * The offset is the suffix and will be normalized during creation. * These IDs can be normalized to a {@code ZoneOffset} using {@code normalized()}. *
* The third type of ID are region-based IDs. A region-based ID must be of * two or more characters, and not start with 'UTC', 'GMT', 'UT' '+' or '-'. * Region-based IDs are defined by configuration, see {@link ZoneRulesProvider}. * The configuration focuses on providing the lookup from the ID to the * underlying {@code ZoneRules}. *
* Time-zone rules are defined by governments and change frequently. * There are a number of organizations, known here as groups, that monitor * time-zone changes and collate them. * The default group is the IANA Time Zone Database (TZDB). * Other organizations include IATA (the airline industry body) and Microsoft. *
* Each group defines its own format for the region ID it provides. * The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'. * TZDB IDs take precedence over other groups. *
* It is strongly recommended that the group name is included in all IDs supplied by * groups other than TZDB to avoid conflicts. For example, IATA airline time-zone * region IDs are typically the same as the three letter airport code. * However, the airport of Utrecht has the code 'UTC', which is obviously a conflict. * The recommended format for region IDs from groups other than TZDB is 'group~region'. * Thus if IATA data were defined, Utrecht airport would be 'IATA~UTC'. * *
* A {@code ZoneId} can be deserialized in a Java Runtime where the ID is unknown. * For example, if a server-side Java Runtime has been updated with a new zone ID, but * the client-side Java Runtime has not been updated. In this case, the {@code ZoneId} * object will exist, and can be queried using {@code getId}, {@code equals}, * {@code hashCode}, {@code toString}, {@code getDisplayName} and {@code normalized}. * However, any call to {@code getRules} will fail with {@code ZoneRulesException}. * This approach is designed to allow a {@link ZonedDateTime} to be loaded and * queried, but not modified, on a Java Runtime with incomplete time-zone information. * *
* This is a value-based * class; use of identity-sensitive operations (including reference equality * ({@code ==}), identity hash code, or synchronization) on instances of * {@code ZoneId} may have unpredictable results and should be avoided. * The {@code equals} method should be used for comparisons. * * @implSpec * This abstract class has two implementations, both of which are immutable and thread-safe. * One implementation models region-based IDs, the other is {@code ZoneOffset} modelling * offset-based IDs. This difference is visible in serialization. * * @since 1.8 */ public abstract class ZoneId implements Serializable { /** * A map of zone overrides to enable the short time-zone names to be used. *
* Use of short zone IDs has been deprecated in {@code java.util.TimeZone}. * This map allows the IDs to continue to be used via the * {@link #of(String, Map)} factory method. *
* This map contains a mapping of the IDs that is in line with TZDB 2005r and * later, where 'EST', 'MST' and 'HST' map to IDs which do not include daylight * savings. *
* This maps as follows: *
* This queries {@link TimeZone#getDefault()} to find the default time-zone * and converts it to a {@code ZoneId}. If the system default time-zone is changed, * then the result of this method will also change. * * @return the zone ID, not null * @throws DateTimeException if the converted zone ID has an invalid format * @throws ZoneRulesException if the converted zone region ID cannot be found */ public static ZoneId systemDefault() { return TimeZone.getDefault().toZoneId(); } /** * Gets the set of available zone IDs. *
* This set includes the string form of all available region-based IDs. * Offset-based zone IDs are not included in the returned set. * The ID can be passed to {@link #of(String)} to create a {@code ZoneId}. *
* The set of zone IDs can increase over time, although in a typical application
* the set of IDs is fixed. Each call to this method is thread-safe.
*
* @return a modifiable copy of the set of zone IDs, not null
*/
public static Set
* 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 IDs.
* This method allows a map of string to time-zone to be setup and reused
* within an application.
*
* @param zoneId the time-zone ID, not null
* @param aliasMap a map of alias zone IDs (typically abbreviations) to real zone IDs, not null
* @return the zone ID, not null
* @throws DateTimeException if the zone ID has an invalid format
* @throws ZoneRulesException if the zone ID is a region ID that cannot be found
*/
public static ZoneId of(String zoneId, Map
* This method parses the ID producing a {@code ZoneId} or {@code ZoneOffset}.
* A {@code ZoneOffset} is returned if the ID is 'Z', or starts with '+' or '-'.
* The result will always be a valid ID for which {@link ZoneRules} can be obtained.
*
* Parsing matches the zone ID step by step as follows.
*
* If the prefix is "GMT", "UTC", or "UT" a {@code ZoneId}
* with the prefix and the non-zero offset is returned.
* If the prefix is empty {@code ""} the {@code ZoneOffset} is returned.
*
* @param prefix the time-zone ID, not null
* @param offset the offset, not null
* @return the zone ID, not null
* @throws IllegalArgumentException if the prefix is not one of
* "GMT", "UTC", or "UT", or ""
*/
public static ZoneId ofOffset(String prefix, ZoneOffset offset) {
Objects.requireNonNull(prefix, "prefix");
Objects.requireNonNull(offset, "offset");
if (prefix.length() == 0) {
return offset;
}
if (!prefix.equals("GMT") && !prefix.equals("UTC") && !prefix.equals("UT")) {
throw new IllegalArgumentException("prefix should be GMT, UTC or UT, is: " + prefix);
}
if (offset.getTotalSeconds() != 0) {
prefix = prefix.concat(offset.getId());
}
return new ZoneRegion(prefix, offset.getRules());
}
/**
* Parses the ID, taking a flag to indicate whether {@code ZoneRulesException}
* should be thrown or not, used in deserialization.
*
* @param zoneId the time-zone ID, not null
* @param checkAvailable whether to check if the zone ID is available
* @return the zone ID, not null
* @throws DateTimeException if the ID format is invalid
* @throws ZoneRulesException if checking availability and the ID cannot be found
*/
static ZoneId of(String zoneId, boolean checkAvailable) {
Objects.requireNonNull(zoneId, "zoneId");
if (zoneId.length() <= 1 || zoneId.startsWith("+") || zoneId.startsWith("-")) {
return ZoneOffset.of(zoneId);
} else if (zoneId.startsWith("UTC") || zoneId.startsWith("GMT")) {
return ofWithPrefix(zoneId, 3, checkAvailable);
} else if (zoneId.startsWith("UT")) {
return ofWithPrefix(zoneId, 2, checkAvailable);
}
return ZoneRegion.ofId(zoneId, checkAvailable);
}
/**
* Parse once a prefix is established.
*
* @param zoneId the time-zone ID, not null
* @param prefixLength the length of the prefix, 2 or 3
* @return the zone ID, not null
* @throws DateTimeException if the zone ID has an invalid format
*/
private static ZoneId ofWithPrefix(String zoneId, int prefixLength, boolean checkAvailable) {
String prefix = zoneId.substring(0, prefixLength);
if (zoneId.length() == prefixLength) {
return ofOffset(prefix, ZoneOffset.UTC);
}
if (zoneId.charAt(prefixLength) != '+' && zoneId.charAt(prefixLength) != '-') {
return ZoneRegion.ofId(zoneId, checkAvailable); // drop through to ZoneRulesProvider
}
try {
ZoneOffset offset = ZoneOffset.of(zoneId.substring(prefixLength));
if (offset == ZoneOffset.UTC) {
return ofOffset(prefix, offset);
}
return ofOffset(prefix, offset);
} catch (DateTimeException ex) {
throw new DateTimeException("Invalid ID for offset-based ZoneId: " + zoneId, ex);
}
}
//-----------------------------------------------------------------------
/**
* Obtains an instance of {@code ZoneId} from a temporal object.
*
* This obtains a zone based on the specified temporal.
* A {@code TemporalAccessor} represents an arbitrary set of date and time information,
* which this factory converts to an instance of {@code ZoneId}.
*
* A {@code TemporalAccessor} represents some form of date and time information.
* This factory converts the arbitrary temporal object to an instance of {@code ZoneId}.
*
* The conversion will try to obtain the zone in a way that favours region-based
* zones over offset-based zones using {@link TemporalQueries#zone()}.
*
* This method matches the signature of the functional interface {@link TemporalQuery}
* allowing it to be used as a query via method reference, {@code ZoneId::from}.
*
* @param temporal the temporal object to convert, not null
* @return the zone ID, not null
* @throws DateTimeException if unable to convert to a {@code ZoneId}
*/
public static ZoneId from(TemporalAccessor temporal) {
ZoneId obj = temporal.query(TemporalQueries.zone());
if (obj == null) {
throw new DateTimeException("Unable to obtain ZoneId from TemporalAccessor: " +
temporal + " of type " + temporal.getClass().getName());
}
return obj;
}
//-----------------------------------------------------------------------
/**
* Constructor only accessible within the package.
*/
ZoneId() {
if (getClass() != ZoneOffset.class && getClass() != ZoneRegion.class) {
throw new AssertionError("Invalid subclass");
}
}
//-----------------------------------------------------------------------
/**
* Gets the unique time-zone ID.
*
* This ID uniquely defines this object.
* The format of an offset based ID is defined by {@link ZoneOffset#getId()}.
*
* @return the time-zone unique ID, not null
*/
public abstract String getId();
//-----------------------------------------------------------------------
/**
* Gets the textual representation of the zone, such as 'British Time' or
* '+02:00'.
*
* This returns the textual name used to identify the time-zone ID,
* suitable for presentation to the user.
* The parameters control the style of the returned text and the locale.
*
* If no textual mapping is found then the {@link #getId() full ID} is returned.
*
* @param style the length of the text required, not null
* @param locale the locale to use, not null
* @return the text value of the zone, not null
*/
public String getDisplayName(TextStyle style, Locale locale) {
return new DateTimeFormatterBuilder().appendZoneText(style).toFormatter(locale).format(toTemporal());
}
/**
* Converts this zone to a {@code TemporalAccessor}.
*
* A {@code ZoneId} can be fully represented as a {@code TemporalAccessor}.
* However, the interface is not implemented by this class as most of the
* methods on the interface have no meaning to {@code ZoneId}.
*
* The returned temporal has no supported fields, with the query method
* supporting the return of the zone using {@link TemporalQueries#zoneId()}.
*
* @return a temporal equivalent to this zone, not null
*/
private TemporalAccessor toTemporal() {
return new TemporalAccessor() {
@Override
public boolean isSupported(TemporalField field) {
return false;
}
@Override
public long getLong(TemporalField field) {
throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
}
@SuppressWarnings("unchecked")
@Override
public
* 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 Java Runtime which
* does not have the same rules loaded as the Java Runtime that stored it.
* In this case, calling this method will throw a {@code ZoneRulesException}.
*
* The rules are supplied by {@link ZoneRulesProvider}. An advanced provider may
* support dynamic updates to the rules without restarting the Java Runtime.
* If so, then the result of this method may change over time.
* Each individual call will be still remain thread-safe.
*
* {@link ZoneOffset} will always return a set of rules where the offset never changes.
*
* @return the rules, not null
* @throws ZoneRulesException if no rules are available for this ID
*/
public abstract ZoneRules getRules();
/**
* Normalizes the time-zone ID, returning a {@code ZoneOffset} where possible.
*
* The returns a normalized {@code ZoneId} that can be used in place of this ID.
* The result will have {@code ZoneRules} equivalent to those returned by this object,
* however the ID returned by {@code getId()} may be different.
*
* The normalization checks if the rules of this {@code ZoneId} have a fixed offset.
* If they do, then the {@code ZoneOffset} equal to that offset is returned.
* Otherwise {@code this} is returned.
*
* @return the time-zone unique ID, not null
*/
public ZoneId normalized() {
try {
ZoneRules rules = getRules();
if (rules.isFixedOffset()) {
return rules.getOffset(Instant.EPOCH);
}
} catch (ZoneRulesException ex) {
// invalid ZoneRegion is not important to this method
}
return this;
}
//-----------------------------------------------------------------------
/**
* Checks if this time-zone ID is equal to another time-zone ID.
*
* The comparison is based on the ID.
*
* @param obj the object to check, null returns false
* @return true if this is equal to the other time-zone ID
*/
@Override
public boolean equals(Object obj) {
if (this == obj) {
return true;
}
if (obj instanceof ZoneId) {
ZoneId other = (ZoneId) obj;
return getId().equals(other.getId());
}
return false;
}
/**
* A hash code for this time-zone ID.
*
* @return a suitable hash code
*/
@Override
public int hashCode() {
return getId().hashCode();
}
//-----------------------------------------------------------------------
/**
* Defend against malicious streams.
*
* @param s the stream to read
* @throws InvalidObjectException always
*/
private void readObject(ObjectInputStream s) throws InvalidObjectException {
throw new InvalidObjectException("Deserialization via serialization delegate");
}
/**
* Outputs this zone as a {@code String}, using the ID.
*
* @return a string representation of this time-zone ID, not null
*/
@Override
public String toString() {
return getId();
}
//-----------------------------------------------------------------------
/**
* Writes the object using a
* dedicated serialized form.
* @serialData
*
* When read back in, the {@code ZoneId} will be created as though using
* {@link #of(String)}, but without any exception in the case where the
* ID has a valid format, but is not in the known set of region-based IDs.
*
* @return the instance of {@code Ser}, not null
*/
// this is here for serialization Javadoc
private Object writeReplace() {
return new Ser(Ser.ZONE_REGION_TYPE, this);
}
abstract void write(DataOutput out) throws IOException;
}
*
*
* @param zoneId the time-zone ID, not null
* @return the zone ID, not null
* @throws DateTimeException if the zone ID has an invalid format
* @throws ZoneRulesException if the zone ID is a region ID that cannot be found
*/
public static ZoneId of(String zoneId) {
return of(zoneId, true);
}
/**
* Obtains an instance of {@code ZoneId} wrapping an offset.
* [A-Za-z][A-Za-z0-9~/._+-]+
* otherwise a {@code DateTimeException} is thrown. If the zone ID is not
* in the configured set of IDs, {@code ZoneRulesException} is thrown.
* The detailed format of the region ID depends on the group supplying the data.
* The default set of data is supplied by the IANA Time Zone Database (TZDB).
* This has region IDs of the form '{area}/{city}', such as 'Europe/Paris' or 'America/New_York'.
* This is compatible with most IDs from {@link java.util.TimeZone}.
*
* out.writeByte(7); // identifies a ZoneId (not ZoneOffset)
* out.writeUTF(getId());
*
*