1 /*
2 * Copyright (c) 2012, 2024, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /*
27 * This file is available under and governed by the GNU General Public
28 * License version 2 only, as published by the Free Software Foundation.
29 * However, the following notice accompanied the original version of this
30 * file:
31 *
32 * Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos
33 *
34 * All rights reserved.
35 *
36 * Redistribution and use in source and binary forms, with or without
37 * modification, are permitted provided that the following conditions are met:
38 *
39 * * Redistributions of source code must retain the above copyright notice,
40 * this list of conditions and the following disclaimer.
41 *
42 * * Redistributions in binary form must reproduce the above copyright notice,
43 * this list of conditions and the following disclaimer in the documentation
44 * and/or other materials provided with the distribution.
45 *
46 * * Neither the name of JSR-310 nor the names of its contributors
47 * may be used to endorse or promote products derived from this software
48 * without specific prior written permission.
49 *
50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
61 */
62 package java.time;
63
64 import java.io.DataOutput;
65 import java.io.IOException;
66 import java.io.InvalidObjectException;
67 import java.io.ObjectInputStream;
68 import java.io.Serializable;
69 import java.time.format.DateTimeFormatterBuilder;
70 import java.time.format.TextStyle;
71 import java.time.temporal.TemporalAccessor;
72 import java.time.temporal.TemporalField;
73 import java.time.temporal.TemporalQueries;
74 import java.time.temporal.TemporalQuery;
75 import java.time.temporal.UnsupportedTemporalTypeException;
76 import java.time.zone.ZoneRules;
77 import java.time.zone.ZoneRulesException;
78 import java.time.zone.ZoneRulesProvider;
79 import java.util.HashSet;
80 import java.util.Locale;
81 import java.util.Map;
82 import java.util.Objects;
83 import java.util.Set;
84 import java.util.TimeZone;
85
86 import static java.util.Map.entry;
87
88 /**
89 * A time-zone ID, such as {@code Europe/Paris}.
90 * <p>
91 * A {@code ZoneId} is used to identify the rules used to convert between
92 * an {@link Instant} and a {@link LocalDateTime}.
93 * There are two distinct types of ID:
94 * <ul>
95 * <li>Fixed offsets - a fully resolved offset from UTC/Greenwich, that uses
96 * the same offset for all local date-times
97 * <li>Geographical regions - an area where a specific set of rules for finding
98 * the offset from UTC/Greenwich apply
99 * </ul>
100 * Most fixed offsets are represented by {@link ZoneOffset}.
101 * Calling {@link #normalized()} on any {@code ZoneId} will ensure that a
102 * fixed offset ID will be represented as a {@code ZoneOffset}.
103 * <p>
104 * The actual rules, describing when and how the offset changes, are defined by {@link ZoneRules}.
105 * This class is simply an ID used to obtain the underlying rules.
106 * This approach is taken because rules are defined by governments and change
107 * frequently, whereas the ID is stable.
108 * <p>
109 * The distinction has other effects. Serializing the {@code ZoneId} will only send
110 * the ID, whereas serializing the rules sends the entire data set.
111 * Similarly, a comparison of two IDs only examines the ID, whereas
112 * a comparison of two rules examines the entire data set.
113 *
114 * <h2>Time-zone IDs</h2>
115 * The ID is unique within the system.
116 * There are three types of ID.
117 * <p>
118 * The simplest type of ID is that from {@code ZoneOffset}.
119 * This consists of 'Z' and IDs starting with '+' or '-'.
120 * <p>
121 * The next type of ID are offset-style IDs with some form of prefix,
122 * such as 'GMT+2' or 'UTC+01:00'.
123 * The recognised prefixes are 'UTC', 'GMT' and 'UT'.
124 * The offset is the suffix and will be normalized during creation.
125 * These IDs can be normalized to a {@code ZoneOffset} using {@code normalized()}.
126 * <p>
127 * The third type of ID are region-based IDs. A region-based ID must be of
128 * two or more characters, and not start with 'UTC', 'GMT', 'UT' '+' or '-'.
129 * Region-based IDs are defined by configuration, see {@link ZoneRulesProvider}.
130 * The configuration focuses on providing the lookup from the ID to the
131 * underlying {@code ZoneRules}.
132 * <p>
133 * Time-zone rules are defined by governments and change frequently.
134 * There are a number of organizations, known here as groups, that monitor
135 * time-zone changes and collate them.
136 * The default group is the IANA Time Zone Database (TZDB).
137 * Other organizations include IATA (the airline industry body) and Microsoft.
138 * <p>
139 * Each group defines its own format for the region ID it provides.
140 * The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'.
141 * TZDB IDs take precedence over other groups.
142 * <p>
143 * It is strongly recommended that the group name is included in all IDs supplied by
144 * groups other than TZDB to avoid conflicts. For example, IATA airline time-zone
145 * region IDs are typically the same as the three letter airport code.
146 * However, the airport of Utrecht has the code 'UTC', which is obviously a conflict.
147 * The recommended format for region IDs from groups other than TZDB is 'group~region'.
148 * Thus if IATA data were defined, Utrecht airport would be 'IATA~UTC'.
149 *
150 * <h2>Serialization</h2>
151 * This class can be serialized and stores the string zone ID in the external form.
152 * The {@code ZoneOffset} subclass uses a dedicated format that only stores the
153 * offset from UTC/Greenwich.
154 * <p>
155 * A {@code ZoneId} can be deserialized in a Java Runtime where the ID is unknown.
156 * For example, if a server-side Java Runtime has been updated with a new zone ID, but
157 * the client-side Java Runtime has not been updated. In this case, the {@code ZoneId}
158 * object will exist, and can be queried using {@code getId}, {@code equals},
159 * {@code hashCode}, {@code toString}, {@code getDisplayName} and {@code normalized}.
160 * However, any call to {@code getRules} will fail with {@code ZoneRulesException}.
161 * This approach is designed to allow a {@link ZonedDateTime} to be loaded and
162 * queried, but not modified, on a Java Runtime with incomplete time-zone information.
163 * <p>
164 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
165 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
166 * as interchangeable and should not use instances for synchronization, mutexes, or
167 * with {@linkplain java.lang.ref.Reference object references}.
168 *
169 * @implSpec
170 * This abstract sealed class permits two implementations, both of which are immutable and
171 * thread-safe. One implementation models region-based IDs, the other is {@code ZoneOffset}
172 * modelling offset-based IDs. This difference is visible in serialization.
173 *
174 * @since 1.8
175 * @sealedGraph
176 */
177 @jdk.internal.ValueBased
178 public abstract sealed class ZoneId implements Serializable permits ZoneOffset, ZoneRegion {
179
180 /**
181 * A map of zone overrides to enable the short time-zone names to be used.
182 * <p>
183 * Use of short zone IDs has been deprecated in {@code java.util.TimeZone}.
184 * This map allows the IDs to continue to be used via the
185 * {@link #of(String, Map)} factory method.
186 * <p>
187 * This map contains a mapping of the IDs that is in line with TZDB 2024b and
188 * later, where 'EST', 'MST' and 'HST' map to IDs which do not include daylight
189 * savings since 1970. This mapping may change in update releases in support of new versions of TZDB.
190 * <p>
191 * This maps as follows:
192 * <ul>
193 * <li>ACT - Australia/Darwin</li>
194 * <li>AET - Australia/Sydney</li>
195 * <li>AGT - America/Argentina/Buenos_Aires</li>
196 * <li>ART - Africa/Cairo</li>
197 * <li>AST - America/Anchorage</li>
198 * <li>BET - America/Sao_Paulo</li>
199 * <li>BST - Asia/Dhaka</li>
200 * <li>CAT - Africa/Harare</li>
201 * <li>CNT - America/St_Johns</li>
202 * <li>CST - America/Chicago</li>
203 * <li>CTT - Asia/Shanghai</li>
204 * <li>EAT - Africa/Addis_Ababa</li>
205 * <li>ECT - Europe/Paris</li>
206 * <li>EST - America/Panama</li>
207 * <li>HST - Pacific/Honolulu</li>
208 * <li>IET - America/Indiana/Indianapolis</li>
209 * <li>IST - Asia/Kolkata</li>
210 * <li>JST - Asia/Tokyo</li>
211 * <li>MIT - Pacific/Apia</li>
212 * <li>MST - America/Phoenix</li>
213 * <li>NET - Asia/Yerevan</li>
214 * <li>NST - Pacific/Auckland</li>
215 * <li>PLT - Asia/Karachi</li>
216 * <li>PNT - America/Phoenix</li>
217 * <li>PRT - America/Puerto_Rico</li>
218 * <li>PST - America/Los_Angeles</li>
219 * <li>SST - Pacific/Guadalcanal</li>
220 * <li>VST - Asia/Ho_Chi_Minh</li>
221 * </ul>
222 * The map is unmodifiable.
223 */
224 public static final Map<String, String> SHORT_IDS = Map.ofEntries(
225 entry("ACT", "Australia/Darwin"),
226 entry("AET", "Australia/Sydney"),
227 entry("AGT", "America/Argentina/Buenos_Aires"),
228 entry("ART", "Africa/Cairo"),
229 entry("AST", "America/Anchorage"),
230 entry("BET", "America/Sao_Paulo"),
231 entry("BST", "Asia/Dhaka"),
232 entry("CAT", "Africa/Harare"),
233 entry("CNT", "America/St_Johns"),
234 entry("CST", "America/Chicago"),
235 entry("CTT", "Asia/Shanghai"),
236 entry("EAT", "Africa/Addis_Ababa"),
237 entry("ECT", "Europe/Paris"),
238 entry("IET", "America/Indiana/Indianapolis"),
239 entry("IST", "Asia/Kolkata"),
240 entry("JST", "Asia/Tokyo"),
241 entry("MIT", "Pacific/Apia"),
242 entry("NET", "Asia/Yerevan"),
243 entry("NST", "Pacific/Auckland"),
244 entry("PLT", "Asia/Karachi"),
245 entry("PNT", "America/Phoenix"),
246 entry("PRT", "America/Puerto_Rico"),
247 entry("PST", "America/Los_Angeles"),
248 entry("SST", "Pacific/Guadalcanal"),
249 entry("VST", "Asia/Ho_Chi_Minh"),
250 entry("EST", "America/Panama"),
251 entry("MST", "America/Phoenix"),
252 entry("HST", "Pacific/Honolulu")
253 );
254 /**
255 * Serialization version.
256 */
257 @java.io.Serial
258 private static final long serialVersionUID = 8352817235686L;
259
260 //-----------------------------------------------------------------------
261 /**
262 * Gets the system default time-zone.
263 * <p>
264 * This queries {@link TimeZone#getDefault()} to find the default time-zone
265 * and converts it to a {@code ZoneId}. If the system default time-zone is changed,
266 * then the result of this method will also change.
267 *
268 * @return the zone ID, not null
269 * @throws DateTimeException if the converted zone ID has an invalid format
270 * @throws ZoneRulesException if the converted zone region ID cannot be found
271 */
272 public static ZoneId systemDefault() {
273 return TimeZone.getDefault().toZoneId();
274 }
275
276 /**
277 * Gets the set of available zone IDs.
278 * <p>
279 * This set includes the string form of all available region-based IDs.
280 * Offset-based zone IDs are not included in the returned set.
281 * The ID can be passed to {@link #of(String)} to create a {@code ZoneId}.
282 * <p>
283 * The set of zone IDs can increase over time, although in a typical application
284 * the set of IDs is fixed. Each call to this method is thread-safe.
285 *
286 * @return a modifiable copy of the set of zone IDs, not null
287 */
288 public static Set<String> getAvailableZoneIds() {
289 return new HashSet<String>(ZoneRulesProvider.getAvailableZoneIds());
290 }
291
292 //-----------------------------------------------------------------------
293 /**
294 * Obtains an instance of {@code ZoneId} using its ID using a map
295 * of aliases to supplement the standard zone IDs.
296 * <p>
297 * Many users of time-zones use short abbreviations, such as PST for
298 * 'Pacific Standard Time' and PDT for 'Pacific Daylight Time'.
299 * These abbreviations are not unique, and so cannot be used as IDs.
300 * This method allows a map of string to time-zone to be setup and reused
301 * within an application.
302 *
303 * @param zoneId the time-zone ID, not null
304 * @param aliasMap a map of alias zone IDs (typically abbreviations) to real zone IDs, not null
305 * @return the zone ID, not null
306 * @throws DateTimeException if the zone ID has an invalid format
307 * @throws ZoneRulesException if the zone ID is a region ID that cannot be found
308 */
309 public static ZoneId of(String zoneId, Map<String, String> aliasMap) {
310 Objects.requireNonNull(zoneId, "zoneId");
311 Objects.requireNonNull(aliasMap, "aliasMap");
312 String id = Objects.requireNonNullElse(aliasMap.get(zoneId), zoneId);
313 return of(id);
314 }
315
316 /**
317 * Obtains an instance of {@code ZoneId} from an ID ensuring that the
318 * ID is valid and available for use.
319 * <p>
320 * This method parses the ID producing a {@code ZoneId} or {@code ZoneOffset}.
321 * A {@code ZoneOffset} is returned if the ID is 'Z', or starts with '+' or '-'.
322 * The result will always be a valid ID for which {@link ZoneRules} can be obtained.
323 * <p>
324 * Parsing matches the zone ID step by step as follows.
325 * <ul>
326 * <li>If the zone ID equals 'Z', the result is {@code ZoneOffset.UTC}.
327 * <li>If the zone ID consists of a single letter, the zone ID is invalid
328 * and {@code DateTimeException} is thrown.
329 * <li>If the zone ID starts with '+' or '-', the ID is parsed as a
330 * {@code ZoneOffset} using {@link ZoneOffset#of(String)}.
331 * <li>If the zone ID equals 'GMT', 'UTC' or 'UT' then the result is a {@code ZoneId}
332 * with the same ID and rules equivalent to {@code ZoneOffset.UTC}.
333 * <li>If the zone ID starts with 'UTC+', 'UTC-', 'GMT+', 'GMT-', 'UT+' or 'UT-'
334 * then the ID is a prefixed offset-based ID. The ID is split in two, with
335 * a two or three letter prefix and a suffix starting with the sign.
336 * The suffix is parsed as a {@link ZoneOffset#of(String) ZoneOffset}.
337 * The result will be a {@code ZoneId} with the specified UTC/GMT/UT prefix
338 * and the normalized offset ID as per {@link ZoneOffset#getId()}.
339 * The rules of the returned {@code ZoneId} will be equivalent to the
340 * parsed {@code ZoneOffset}.
341 * <li>All other IDs are parsed as region-based zone IDs. Region IDs must
342 * match the regular expression {@code [A-Za-z][A-Za-z0-9~/._+-]+}
343 * otherwise a {@code DateTimeException} is thrown. If the zone ID is not
344 * in the configured set of IDs, {@code ZoneRulesException} is thrown.
345 * The detailed format of the region ID depends on the group supplying the data.
346 * The default set of data is supplied by the IANA Time Zone Database (TZDB).
347 * This has region IDs of the form '{area}/{city}', such as 'Europe/Paris' or 'America/New_York'.
348 * This is compatible with most IDs from {@link java.util.TimeZone}.
349 * </ul>
350 *
351 * @param zoneId the time-zone ID, not null
352 * @return the zone ID, not null
353 * @throws DateTimeException if the zone ID has an invalid format
354 * @throws ZoneRulesException if the zone ID is a region ID that cannot be found
355 */
356 public static ZoneId of(String zoneId) {
357 return of(zoneId, true);
358 }
359
360 /**
361 * Obtains an instance of {@code ZoneId} wrapping an offset.
362 * <p>
363 * If the prefix is "GMT", "UTC", or "UT" a {@code ZoneId}
364 * with the prefix and the non-zero offset is returned.
365 * If the prefix is empty {@code ""} the {@code ZoneOffset} is returned.
366 *
367 * @param prefix the time-zone ID, not null
368 * @param offset the offset, not null
369 * @return the zone ID, not null
370 * @throws IllegalArgumentException if the prefix is not one of
371 * "GMT", "UTC", or "UT", or ""
372 */
373 public static ZoneId ofOffset(String prefix, ZoneOffset offset) {
374 Objects.requireNonNull(prefix, "prefix");
375 Objects.requireNonNull(offset, "offset");
376 if (prefix.isEmpty()) {
377 return offset;
378 }
379
380 if (!prefix.equals("GMT") && !prefix.equals("UTC") && !prefix.equals("UT")) {
381 throw new IllegalArgumentException("prefix should be GMT, UTC or UT, is: " + prefix);
382 }
383
384 if (offset.getTotalSeconds() != 0) {
385 prefix = prefix.concat(offset.getId());
386 }
387 return new ZoneRegion(prefix, offset.getRules());
388 }
389
390 /**
391 * Parses the ID, taking a flag to indicate whether {@code ZoneRulesException}
392 * should be thrown or not, used in deserialization.
393 *
394 * @param zoneId the time-zone ID, not null
395 * @param checkAvailable whether to check if the zone ID is available
396 * @return the zone ID, not null
397 * @throws DateTimeException if the ID format is invalid
398 * @throws ZoneRulesException if checking availability and the ID cannot be found
399 */
400 static ZoneId of(String zoneId, boolean checkAvailable) {
401 Objects.requireNonNull(zoneId, "zoneId");
402 if (zoneId.length() <= 1 || zoneId.startsWith("+") || zoneId.startsWith("-")) {
403 return ZoneOffset.of(zoneId);
404 } else if (zoneId.startsWith("UTC") || zoneId.startsWith("GMT")) {
405 return ofWithPrefix(zoneId, 3, checkAvailable);
406 } else if (zoneId.startsWith("UT")) {
407 return ofWithPrefix(zoneId, 2, checkAvailable);
408 }
409 return ZoneRegion.ofId(zoneId, checkAvailable);
410 }
411
412 /**
413 * Parse once a prefix is established.
414 *
415 * @param zoneId the time-zone ID, not null
416 * @param prefixLength the length of the prefix, 2 or 3
417 * @return the zone ID, not null
418 * @throws DateTimeException if the zone ID has an invalid format
419 */
420 private static ZoneId ofWithPrefix(String zoneId, int prefixLength, boolean checkAvailable) {
421 String prefix = zoneId.substring(0, prefixLength);
422 if (zoneId.length() == prefixLength) {
423 return ofOffset(prefix, ZoneOffset.UTC);
424 }
425 if (zoneId.charAt(prefixLength) != '+' && zoneId.charAt(prefixLength) != '-') {
426 return ZoneRegion.ofId(zoneId, checkAvailable); // drop through to ZoneRulesProvider
427 }
428 try {
429 ZoneOffset offset = ZoneOffset.of(zoneId.substring(prefixLength));
430 if (offset == ZoneOffset.UTC) {
431 return ofOffset(prefix, offset);
432 }
433 return ofOffset(prefix, offset);
434 } catch (DateTimeException ex) {
435 throw new DateTimeException("Invalid ID for offset-based ZoneId: " + zoneId, ex);
436 }
437 }
438
439 //-----------------------------------------------------------------------
440 /**
441 * Obtains an instance of {@code ZoneId} from a temporal object.
442 * <p>
443 * This obtains a zone based on the specified temporal.
444 * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
445 * which this factory converts to an instance of {@code ZoneId}.
446 * <p>
447 * A {@code TemporalAccessor} represents some form of date and time information.
448 * This factory converts the arbitrary temporal object to an instance of {@code ZoneId}.
449 * <p>
450 * The conversion will try to obtain the zone in a way that favours region-based
451 * zones over offset-based zones using {@link TemporalQueries#zone()}.
452 * <p>
453 * This method matches the signature of the functional interface {@link TemporalQuery}
454 * allowing it to be used as a query via method reference, {@code ZoneId::from}.
455 *
456 * @param temporal the temporal object to convert, not null
457 * @return the zone ID, not null
458 * @throws DateTimeException if unable to convert to a {@code ZoneId}
459 */
460 public static ZoneId from(TemporalAccessor temporal) {
461 ZoneId obj = temporal.query(TemporalQueries.zone());
462 if (obj == null) {
463 throw new DateTimeException("Unable to obtain ZoneId from TemporalAccessor: " +
464 temporal + " of type " + temporal.getClass().getName());
465 }
466 return obj;
467 }
468
469 //-----------------------------------------------------------------------
470 /**
471 * Constructor only accessible within the package.
472 */
473 ZoneId() {}
474
475 //-----------------------------------------------------------------------
476 /**
477 * Gets the unique time-zone ID.
478 * <p>
479 * This ID uniquely defines this object.
480 * The format of an offset based ID is defined by {@link ZoneOffset#getId()}.
481 *
482 * @return the time-zone unique ID, not null
483 */
484 public abstract String getId();
485
486 //-----------------------------------------------------------------------
487 /**
488 * Gets the textual representation of the zone, such as 'British Time' or
489 * '+02:00'.
490 * <p>
491 * This returns the textual name used to identify the time-zone ID,
492 * suitable for presentation to the user.
493 * The parameters control the style of the returned text and the locale.
494 * <p>
495 * If no textual mapping is found then the {@link #getId() full ID} is returned.
496 *
497 * @param style the length of the text required, not null
498 * @param locale the locale to use, not null
499 * @return the text value of the zone, not null
500 */
501 public String getDisplayName(TextStyle style, Locale locale) {
502 return new DateTimeFormatterBuilder().appendZoneText(style).toFormatter(locale).format(toTemporal());
503 }
504
505 /**
506 * Converts this zone to a {@code TemporalAccessor}.
507 * <p>
508 * A {@code ZoneId} can be fully represented as a {@code TemporalAccessor}.
509 * However, the interface is not implemented by this class as most of the
510 * methods on the interface have no meaning to {@code ZoneId}.
511 * <p>
512 * The returned temporal has no supported fields, with the query method
513 * supporting the return of the zone using {@link TemporalQueries#zoneId()}.
514 *
515 * @return a temporal equivalent to this zone, not null
516 */
517 private TemporalAccessor toTemporal() {
518 return new TemporalAccessor() {
519 @Override
520 public boolean isSupported(TemporalField field) {
521 return false;
522 }
523 @Override
524 public long getLong(TemporalField field) {
525 throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
526 }
527 @SuppressWarnings("unchecked")
528 @Override
529 public <R> R query(TemporalQuery<R> query) {
530 if (query == TemporalQueries.zoneId()) {
531 return (R) ZoneId.this;
532 }
533 return TemporalAccessor.super.query(query);
534 }
535 };
536 }
537
538 //-----------------------------------------------------------------------
539 /**
540 * Gets the time-zone rules for this ID allowing calculations to be performed.
541 * <p>
542 * The rules provide the functionality associated with a time-zone,
543 * such as finding the offset for a given instant or local date-time.
544 * <p>
545 * A time-zone can be invalid if it is deserialized in a Java Runtime which
546 * does not have the same rules loaded as the Java Runtime that stored it.
547 * In this case, calling this method will throw a {@code ZoneRulesException}.
548 * <p>
549 * The rules are supplied by {@link ZoneRulesProvider}. An advanced provider may
550 * support dynamic updates to the rules without restarting the Java Runtime.
551 * If so, then the result of this method may change over time.
552 * Each individual call will be still remain thread-safe.
553 * <p>
554 * {@link ZoneOffset} will always return a set of rules where the offset never changes.
555 *
556 * @return the rules, not null
557 * @throws ZoneRulesException if no rules are available for this ID
558 */
559 public abstract ZoneRules getRules();
560
561 /**
562 * Normalizes the time-zone ID, returning a {@code ZoneOffset} where possible.
563 * <p>
564 * The returns a normalized {@code ZoneId} that can be used in place of this ID.
565 * The result will have {@code ZoneRules} equivalent to those returned by this object,
566 * however the ID returned by {@code getId()} may be different.
567 * <p>
568 * The normalization checks if the rules of this {@code ZoneId} have a fixed offset.
569 * If they do, then the {@code ZoneOffset} equal to that offset is returned.
570 * Otherwise {@code this} is returned.
571 *
572 * @return the time-zone unique ID, not null
573 */
574 public ZoneId normalized() {
575 try {
576 ZoneRules rules = getRules();
577 if (rules.isFixedOffset()) {
578 return rules.getOffset(Instant.EPOCH);
579 }
580 } catch (ZoneRulesException ex) {
581 // invalid ZoneRegion is not important to this method
582 }
583 return this;
584 }
585
586 /**
587 * Get the effective offset for an instant at the given epochSecond.
588 */
589 /* package-private */ abstract ZoneOffset getOffset(long epochSecond);
590
591 //-----------------------------------------------------------------------
592 /**
593 * Checks if this time-zone ID is equal to another time-zone ID.
594 * <p>
595 * The comparison is based on the ID.
596 *
597 * @param obj the object to check, null returns false
598 * @return true if this is equal to the other time-zone ID
599 */
600 @Override
601 public boolean equals(Object obj) {
602 if (this == obj) {
603 return true;
604 }
605 return (obj instanceof ZoneId other)
606 && getId().equals(other.getId());
607 }
608
609 /**
610 * A hash code for this time-zone ID.
611 *
612 * @return a suitable hash code
613 */
614 @Override
615 public int hashCode() {
616 return getId().hashCode();
617 }
618
619 //-----------------------------------------------------------------------
620 /**
621 * Defend against malicious streams.
622 *
623 * @param s the stream to read
624 * @throws InvalidObjectException always
625 */
626 @java.io.Serial
627 private void readObject(ObjectInputStream s) throws InvalidObjectException {
628 throw new InvalidObjectException("Deserialization via serialization delegate");
629 }
630
631 /**
632 * Outputs this zone as a {@code String}, using the ID.
633 *
634 * @return a string representation of this time-zone ID, not null
635 */
636 @Override
637 public String toString() {
638 return getId();
639 }
640
641 //-----------------------------------------------------------------------
642 /**
643 * Writes the object using a
644 * <a href="{@docRoot}/serialized-form.html#java.time.Ser">dedicated serialized form</a>.
645 * @serialData
646 * <pre>
647 * out.writeByte(7); // identifies a ZoneId (not ZoneOffset)
648 * out.writeUTF(getId());
649 * </pre>
650 * <p>
651 * When read back in, the {@code ZoneId} will be created as though using
652 * {@link #of(String)}, but without any exception in the case where the
653 * ID has a valid format, but is not in the known set of region-based IDs.
654 *
655 * @return the instance of {@code Ser}, not null
656 */
657 // this is here for serialization Javadoc
658 @java.io.Serial
659 private Object writeReplace() {
660 return new Ser(Ser.ZONE_REGION_TYPE, this);
661 }
662
663 abstract void write(DataOutput out) throws IOException;
664
665 }