View Javadoc
1   /*
2    * Copyright (c) 2012, 2013, 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.Collections;
80  import java.util.HashMap;
81  import java.util.Locale;
82  import java.util.Map;
83  import java.util.Objects;
84  import java.util.Set;
85  import java.util.TimeZone;
86  
87  /**
88   * A time-zone ID, such as {@code Europe/Paris}.
89   * <p>
90   * A {@code ZoneId} is used to identify the rules used to convert between
91   * an {@link Instant} and a {@link LocalDateTime}.
92   * There are two distinct types of ID:
93   * <ul>
94   * <li>Fixed offsets - a fully resolved offset from UTC/Greenwich, that uses
95   *  the same offset for all local date-times
96   * <li>Geographical regions - an area where a specific set of rules for finding
97   *  the offset from UTC/Greenwich apply
98   * </ul>
99   * Most fixed offsets are represented by {@link ZoneOffset}.
100  * Calling {@link #normalized()} on any {@code ZoneId} will ensure that a
101  * fixed offset ID will be represented as a {@code ZoneOffset}.
102  * <p>
103  * The actual rules, describing when and how the offset changes, are defined by {@link ZoneRules}.
104  * This class is simply an ID used to obtain the underlying rules.
105  * This approach is taken because rules are defined by governments and change
106  * frequently, whereas the ID is stable.
107  * <p>
108  * The distinction has other effects. Serializing the {@code ZoneId} will only send
109  * the ID, whereas serializing the rules sends the entire data set.
110  * Similarly, a comparison of two IDs only examines the ID, whereas
111  * a comparison of two rules examines the entire data set.
112  *
113  * <h3>Time-zone IDs</h3>
114  * The ID is unique within the system.
115  * There are three types of ID.
116  * <p>
117  * The simplest type of ID is that from {@code ZoneOffset}.
118  * This consists of 'Z' and IDs starting with '+' or '-'.
119  * <p>
120  * The next type of ID are offset-style IDs with some form of prefix,
121  * such as 'GMT+2' or 'UTC+01:00'.
122  * The recognised prefixes are 'UTC', 'GMT' and 'UT'.
123  * The offset is the suffix and will be normalized during creation.
124  * These IDs can be normalized to a {@code ZoneOffset} using {@code normalized()}.
125  * <p>
126  * The third type of ID are region-based IDs. A region-based ID must be of
127  * two or more characters, and not start with 'UTC', 'GMT', 'UT' '+' or '-'.
128  * Region-based IDs are defined by configuration, see {@link ZoneRulesProvider}.
129  * The configuration focuses on providing the lookup from the ID to the
130  * underlying {@code ZoneRules}.
131  * <p>
132  * Time-zone rules are defined by governments and change frequently.
133  * There are a number of organizations, known here as groups, that monitor
134  * time-zone changes and collate them.
135  * The default group is the IANA Time Zone Database (TZDB).
136  * Other organizations include IATA (the airline industry body) and Microsoft.
137  * <p>
138  * Each group defines its own format for the region ID it provides.
139  * The TZDB group defines IDs such as 'Europe/London' or 'America/New_York'.
140  * TZDB IDs take precedence over other groups.
141  * <p>
142  * It is strongly recommended that the group name is included in all IDs supplied by
143  * groups other than TZDB to avoid conflicts. For example, IATA airline time-zone
144  * region IDs are typically the same as the three letter airport code.
145  * However, the airport of Utrecht has the code 'UTC', which is obviously a conflict.
146  * The recommended format for region IDs from groups other than TZDB is 'group~region'.
147  * Thus if IATA data were defined, Utrecht airport would be 'IATA~UTC'.
148  *
149  * <h3>Serialization</h3>
150  * This class can be serialized and stores the string zone ID in the external form.
151  * The {@code ZoneOffset} subclass uses a dedicated format that only stores the
152  * offset from UTC/Greenwich.
153  * <p>
154  * A {@code ZoneId} can be deserialized in a Java Runtime where the ID is unknown.
155  * For example, if a server-side Java Runtime has been updated with a new zone ID, but
156  * the client-side Java Runtime has not been updated. In this case, the {@code ZoneId}
157  * object will exist, and can be queried using {@code getId}, {@code equals},
158  * {@code hashCode}, {@code toString}, {@code getDisplayName} and {@code normalized}.
159  * However, any call to {@code getRules} will fail with {@code ZoneRulesException}.
160  * This approach is designed to allow a {@link ZonedDateTime} to be loaded and
161  * queried, but not modified, on a Java Runtime with incomplete time-zone information.
162  *
163  * <p>
164  * This is a <a href="{@docRoot}/java/lang/doc-files/ValueBased.html">value-based</a>
165  * class; use of identity-sensitive operations (including reference equality
166  * ({@code ==}), identity hash code, or synchronization) on instances of
167  * {@code ZoneId} may have unpredictable results and should be avoided.
168  * The {@code equals} method should be used for comparisons.
169  *
170  * @implSpec
171  * This abstract class has two implementations, both of which are immutable and thread-safe.
172  * One implementation models region-based IDs, the other is {@code ZoneOffset} modelling
173  * offset-based IDs. This difference is visible in serialization.
174  *
175  * @since 1.8
176  */
177 public abstract class ZoneId implements Serializable {
178 
179     /**
180      * A map of zone overrides to enable the short time-zone names to be used.
181      * <p>
182      * Use of short zone IDs has been deprecated in {@code java.util.TimeZone}.
183      * This map allows the IDs to continue to be used via the
184      * {@link #of(String, Map)} factory method.
185      * <p>
186      * This map contains a mapping of the IDs that is in line with TZDB 2005r and
187      * later, where 'EST', 'MST' and 'HST' map to IDs which do not include daylight
188      * savings.
189      * <p>
190      * This maps as follows:
191      * <ul>
192      * <li>EST - -05:00</li>
193      * <li>HST - -10:00</li>
194      * <li>MST - -07:00</li>
195      * <li>ACT - Australia/Darwin</li>
196      * <li>AET - Australia/Sydney</li>
197      * <li>AGT - America/Argentina/Buenos_Aires</li>
198      * <li>ART - Africa/Cairo</li>
199      * <li>AST - America/Anchorage</li>
200      * <li>BET - America/Sao_Paulo</li>
201      * <li>BST - Asia/Dhaka</li>
202      * <li>CAT - Africa/Harare</li>
203      * <li>CNT - America/St_Johns</li>
204      * <li>CST - America/Chicago</li>
205      * <li>CTT - Asia/Shanghai</li>
206      * <li>EAT - Africa/Addis_Ababa</li>
207      * <li>ECT - Europe/Paris</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>NET - Asia/Yerevan</li>
213      * <li>NST - Pacific/Auckland</li>
214      * <li>PLT - Asia/Karachi</li>
215      * <li>PNT - America/Phoenix</li>
216      * <li>PRT - America/Puerto_Rico</li>
217      * <li>PST - America/Los_Angeles</li>
218      * <li>SST - Pacific/Guadalcanal</li>
219      * <li>VST - Asia/Ho_Chi_Minh</li>
220      * </ul>
221      * The map is unmodifiable.
222      */
223     public static final Map<String, String> SHORT_IDS;
224     static {
225         Map<String, String> map = new HashMap<>(64);
226         map.put("ACT", "Australia/Darwin");
227         map.put("AET", "Australia/Sydney");
228         map.put("AGT", "America/Argentina/Buenos_Aires");
229         map.put("ART", "Africa/Cairo");
230         map.put("AST", "America/Anchorage");
231         map.put("BET", "America/Sao_Paulo");
232         map.put("BST", "Asia/Dhaka");
233         map.put("CAT", "Africa/Harare");
234         map.put("CNT", "America/St_Johns");
235         map.put("CST", "America/Chicago");
236         map.put("CTT", "Asia/Shanghai");
237         map.put("EAT", "Africa/Addis_Ababa");
238         map.put("ECT", "Europe/Paris");
239         map.put("IET", "America/Indiana/Indianapolis");
240         map.put("IST", "Asia/Kolkata");
241         map.put("JST", "Asia/Tokyo");
242         map.put("MIT", "Pacific/Apia");
243         map.put("NET", "Asia/Yerevan");
244         map.put("NST", "Pacific/Auckland");
245         map.put("PLT", "Asia/Karachi");
246         map.put("PNT", "America/Phoenix");
247         map.put("PRT", "America/Puerto_Rico");
248         map.put("PST", "America/Los_Angeles");
249         map.put("SST", "Pacific/Guadalcanal");
250         map.put("VST", "Asia/Ho_Chi_Minh");
251         map.put("EST", "-05:00");
252         map.put("MST", "-07:00");
253         map.put("HST", "-10:00");
254         SHORT_IDS = Collections.unmodifiableMap(map);
255     }
256     /**
257      * Serialization version.
258      */
259     private static final long serialVersionUID = 8352817235686L;
260 
261     //-----------------------------------------------------------------------
262     /**
263      * Gets the system default time-zone.
264      * <p>
265      * This queries {@link TimeZone#getDefault()} to find the default time-zone
266      * and converts it to a {@code ZoneId}. If the system default time-zone is changed,
267      * then the result of this method will also change.
268      *
269      * @return the zone ID, not null
270      * @throws DateTimeException if the converted zone ID has an invalid format
271      * @throws ZoneRulesException if the converted zone region ID cannot be found
272      */
273     public static ZoneId systemDefault() {
274         return TimeZone.getDefault().toZoneId();
275     }
276 
277     /**
278      * Gets the set of available zone IDs.
279      * <p>
280      * This set includes the string form of all available region-based IDs.
281      * Offset-based zone IDs are not included in the returned set.
282      * The ID can be passed to {@link #of(String)} to create a {@code ZoneId}.
283      * <p>
284      * The set of zone IDs can increase over time, although in a typical application
285      * the set of IDs is fixed. Each call to this method is thread-safe.
286      *
287      * @return a modifiable copy of the set of zone IDs, not null
288      */
289     public static Set<String> getAvailableZoneIds() {
290         return ZoneRulesProvider.getAvailableZoneIds();
291     }
292 
293     //-----------------------------------------------------------------------
294     /**
295      * Obtains an instance of {@code ZoneId} using its ID using a map
296      * of aliases to supplement the standard zone IDs.
297      * <p>
298      * Many users of time-zones use short abbreviations, such as PST for
299      * 'Pacific Standard Time' and PDT for 'Pacific Daylight Time'.
300      * These abbreviations are not unique, and so cannot be used as IDs.
301      * This method allows a map of string to time-zone to be setup and reused
302      * within an application.
303      *
304      * @param zoneId  the time-zone ID, not null
305      * @param aliasMap  a map of alias zone IDs (typically abbreviations) to real zone IDs, not null
306      * @return the zone ID, not null
307      * @throws DateTimeException if the zone ID has an invalid format
308      * @throws ZoneRulesException if the zone ID is a region ID that cannot be found
309      */
310     public static ZoneId of(String zoneId, Map<String, String> aliasMap) {
311         Objects.requireNonNull(zoneId, "zoneId");
312         Objects.requireNonNull(aliasMap, "aliasMap");
313         String id = aliasMap.get(zoneId);
314         id = (id != null ? id : zoneId);
315         return of(id);
316     }
317 
318     /**
319      * Obtains an instance of {@code ZoneId} from an ID ensuring that the
320      * ID is valid and available for use.
321      * <p>
322      * This method parses the ID producing a {@code ZoneId} or {@code ZoneOffset}.
323      * A {@code ZoneOffset} is returned if the ID is 'Z', or starts with '+' or '-'.
324      * The result will always be a valid ID for which {@link ZoneRules} can be obtained.
325      * <p>
326      * Parsing matches the zone ID step by step as follows.
327      * <ul>
328      * <li>If the zone ID equals 'Z', the result is {@code ZoneOffset.UTC}.
329      * <li>If the zone ID consists of a single letter, the zone ID is invalid
330      *  and {@code DateTimeException} is thrown.
331      * <li>If the zone ID starts with '+' or '-', the ID is parsed as a
332      *  {@code ZoneOffset} using {@link ZoneOffset#of(String)}.
333      * <li>If the zone ID equals 'GMT', 'UTC' or 'UT' then the result is a {@code ZoneId}
334      *  with the same ID and rules equivalent to {@code ZoneOffset.UTC}.
335      * <li>If the zone ID starts with 'UTC+', 'UTC-', 'GMT+', 'GMT-', 'UT+' or 'UT-'
336      *  then the ID is a prefixed offset-based ID. The ID is split in two, with
337      *  a two or three letter prefix and a suffix starting with the sign.
338      *  The suffix is parsed as a {@link ZoneOffset#of(String) ZoneOffset}.
339      *  The result will be a {@code ZoneId} with the specified UTC/GMT/UT prefix
340      *  and the normalized offset ID as per {@link ZoneOffset#getId()}.
341      *  The rules of the returned {@code ZoneId} will be equivalent to the
342      *  parsed {@code ZoneOffset}.
343      * <li>All other IDs are parsed as region-based zone IDs. Region IDs must
344      *  match the regular expression <code>[A-Za-z][A-Za-z0-9~/._+-]+</code>
345      *  otherwise a {@code DateTimeException} is thrown. If the zone ID is not
346      *  in the configured set of IDs, {@code ZoneRulesException} is thrown.
347      *  The detailed format of the region ID depends on the group supplying the data.
348      *  The default set of data is supplied by the IANA Time Zone Database (TZDB).
349      *  This has region IDs of the form '{area}/{city}', such as 'Europe/Paris' or 'America/New_York'.
350      *  This is compatible with most IDs from {@link java.util.TimeZone}.
351      * </ul>
352      *
353      * @param zoneId  the time-zone ID, not null
354      * @return the zone ID, not null
355      * @throws DateTimeException if the zone ID has an invalid format
356      * @throws ZoneRulesException if the zone ID is a region ID that cannot be found
357      */
358     public static ZoneId of(String zoneId) {
359         return of(zoneId, true);
360     }
361 
362     /**
363      * Obtains an instance of {@code ZoneId} wrapping an offset.
364      * <p>
365      * If the prefix is "GMT", "UTC", or "UT" a {@code ZoneId}
366      * with the prefix and the non-zero offset is returned.
367      * If the prefix is empty {@code ""} the {@code ZoneOffset} is returned.
368      *
369      * @param prefix  the time-zone ID, not null
370      * @param offset  the offset, not null
371      * @return the zone ID, not null
372      * @throws IllegalArgumentException if the prefix is not one of
373      *     "GMT", "UTC", or "UT", or ""
374      */
375     public static ZoneId ofOffset(String prefix, ZoneOffset offset) {
376         Objects.requireNonNull(prefix, "prefix");
377         Objects.requireNonNull(offset, "offset");
378         if (prefix.length() == 0) {
379             return offset;
380         }
381 
382         if (!prefix.equals("GMT") && !prefix.equals("UTC") && !prefix.equals("UT")) {
383              throw new IllegalArgumentException("prefix should be GMT, UTC or UT, is: " + prefix);
384         }
385 
386         if (offset.getTotalSeconds() != 0) {
387             prefix = prefix.concat(offset.getId());
388         }
389         return new ZoneRegion(prefix, offset.getRules());
390     }
391 
392     /**
393      * Parses the ID, taking a flag to indicate whether {@code ZoneRulesException}
394      * should be thrown or not, used in deserialization.
395      *
396      * @param zoneId  the time-zone ID, not null
397      * @param checkAvailable  whether to check if the zone ID is available
398      * @return the zone ID, not null
399      * @throws DateTimeException if the ID format is invalid
400      * @throws ZoneRulesException if checking availability and the ID cannot be found
401      */
402     static ZoneId of(String zoneId, boolean checkAvailable) {
403         Objects.requireNonNull(zoneId, "zoneId");
404         if (zoneId.length() <= 1 || zoneId.startsWith("+") || zoneId.startsWith("-")) {
405             return ZoneOffset.of(zoneId);
406         } else if (zoneId.startsWith("UTC") || zoneId.startsWith("GMT")) {
407             return ofWithPrefix(zoneId, 3, checkAvailable);
408         } else if (zoneId.startsWith("UT")) {
409             return ofWithPrefix(zoneId, 2, checkAvailable);
410         }
411         return ZoneRegion.ofId(zoneId, checkAvailable);
412     }
413 
414     /**
415      * Parse once a prefix is established.
416      *
417      * @param zoneId  the time-zone ID, not null
418      * @param prefixLength  the length of the prefix, 2 or 3
419      * @return the zone ID, not null
420      * @throws DateTimeException if the zone ID has an invalid format
421      */
422     private static ZoneId ofWithPrefix(String zoneId, int prefixLength, boolean checkAvailable) {
423         String prefix = zoneId.substring(0, prefixLength);
424         if (zoneId.length() == prefixLength) {
425             return ofOffset(prefix, ZoneOffset.UTC);
426         }
427         if (zoneId.charAt(prefixLength) != '+' && zoneId.charAt(prefixLength) != '-') {
428             return ZoneRegion.ofId(zoneId, checkAvailable);  // drop through to ZoneRulesProvider
429         }
430         try {
431             ZoneOffset offset = ZoneOffset.of(zoneId.substring(prefixLength));
432             if (offset == ZoneOffset.UTC) {
433                 return ofOffset(prefix, offset);
434             }
435             return ofOffset(prefix, offset);
436         } catch (DateTimeException ex) {
437             throw new DateTimeException("Invalid ID for offset-based ZoneId: " + zoneId, ex);
438         }
439     }
440 
441     //-----------------------------------------------------------------------
442     /**
443      * Obtains an instance of {@code ZoneId} from a temporal object.
444      * <p>
445      * This obtains a zone based on the specified temporal.
446      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
447      * which this factory converts to an instance of {@code ZoneId}.
448      * <p>
449      * A {@code TemporalAccessor} represents some form of date and time information.
450      * This factory converts the arbitrary temporal object to an instance of {@code ZoneId}.
451      * <p>
452      * The conversion will try to obtain the zone in a way that favours region-based
453      * zones over offset-based zones using {@link TemporalQueries#zone()}.
454      * <p>
455      * This method matches the signature of the functional interface {@link TemporalQuery}
456      * allowing it to be used in queries via method reference, {@code ZoneId::from}.
457      *
458      * @param temporal  the temporal object to convert, not null
459      * @return the zone ID, not null
460      * @throws DateTimeException if unable to convert to a {@code ZoneId}
461      */
462     public static ZoneId from(TemporalAccessor temporal) {
463         ZoneId obj = temporal.query(TemporalQueries.zone());
464         if (obj == null) {
465             throw new DateTimeException("Unable to obtain ZoneId from TemporalAccessor: " +
466                     temporal + " of type " + temporal.getClass().getName());
467         }
468         return obj;
469     }
470 
471     //-----------------------------------------------------------------------
472     /**
473      * Constructor only accessible within the package.
474      */
475     ZoneId() {
476         if (getClass() != ZoneOffset.class && getClass() != ZoneRegion.class) {
477             throw new AssertionError("Invalid subclass");
478         }
479     }
480 
481     //-----------------------------------------------------------------------
482     /**
483      * Gets the unique time-zone ID.
484      * <p>
485      * This ID uniquely defines this object.
486      * The format of an offset based ID is defined by {@link ZoneOffset#getId()}.
487      *
488      * @return the time-zone unique ID, not null
489      */
490     public abstract String getId();
491 
492     //-----------------------------------------------------------------------
493     /**
494      * Gets the textual representation of the zone, such as 'British Time' or
495      * '+02:00'.
496      * <p>
497      * This returns the textual name used to identify the time-zone ID,
498      * suitable for presentation to the user.
499      * The parameters control the style of the returned text and the locale.
500      * <p>
501      * If no textual mapping is found then the {@link #getId() full ID} is returned.
502      *
503      * @param style  the length of the text required, not null
504      * @param locale  the locale to use, not null
505      * @return the text value of the zone, not null
506      */
507     public String getDisplayName(TextStyle style, Locale locale) {
508         return new DateTimeFormatterBuilder().appendZoneText(style).toFormatter(locale).format(toTemporal());
509     }
510 
511     /**
512      * Converts this zone to a {@code TemporalAccessor}.
513      * <p>
514      * A {@code ZoneId} can be fully represented as a {@code TemporalAccessor}.
515      * However, the interface is not implemented by this class as most of the
516      * methods on the interface have no meaning to {@code ZoneId}.
517      * <p>
518      * The returned temporal has no supported fields, with the query method
519      * supporting the return of the zone using {@link TemporalQueries#zoneId()}.
520      *
521      * @return a temporal equivalent to this zone, not null
522      */
523     private TemporalAccessor toTemporal() {
524         return new TemporalAccessor() {
525             @Override
526             public boolean isSupported(TemporalField field) {
527                 return false;
528             }
529             @Override
530             public long getLong(TemporalField field) {
531                 throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
532             }
533             @SuppressWarnings("unchecked")
534             @Override
535             public <R> R query(TemporalQuery<R> query) {
536                 if (query == TemporalQueries.zoneId()) {
537                     return (R) ZoneId.this;
538                 }
539                 return TemporalAccessor.super.query(query);
540             }
541         };
542     }
543 
544     //-----------------------------------------------------------------------
545     /**
546      * Gets the time-zone rules for this ID allowing calculations to be performed.
547      * <p>
548      * The rules provide the functionality associated with a time-zone,
549      * such as finding the offset for a given instant or local date-time.
550      * <p>
551      * A time-zone can be invalid if it is deserialized in a Java Runtime which
552      * does not have the same rules loaded as the Java Runtime that stored it.
553      * In this case, calling this method will throw a {@code ZoneRulesException}.
554      * <p>
555      * The rules are supplied by {@link ZoneRulesProvider}. An advanced provider may
556      * support dynamic updates to the rules without restarting the Java Runtime.
557      * If so, then the result of this method may change over time.
558      * Each individual call will be still remain thread-safe.
559      * <p>
560      * {@link ZoneOffset} will always return a set of rules where the offset never changes.
561      *
562      * @return the rules, not null
563      * @throws ZoneRulesException if no rules are available for this ID
564      */
565     public abstract ZoneRules getRules();
566 
567     /**
568      * Normalizes the time-zone ID, returning a {@code ZoneOffset} where possible.
569      * <p>
570      * The returns a normalized {@code ZoneId} that can be used in place of this ID.
571      * The result will have {@code ZoneRules} equivalent to those returned by this object,
572      * however the ID returned by {@code getId()} may be different.
573      * <p>
574      * The normalization checks if the rules of this {@code ZoneId} have a fixed offset.
575      * If they do, then the {@code ZoneOffset} equal to that offset is returned.
576      * Otherwise {@code this} is returned.
577      *
578      * @return the time-zone unique ID, not null
579      */
580     public ZoneId normalized() {
581         try {
582             ZoneRules rules = getRules();
583             if (rules.isFixedOffset()) {
584                 return rules.getOffset(Instant.EPOCH);
585             }
586         } catch (ZoneRulesException ex) {
587             // invalid ZoneRegion is not important to this method
588         }
589         return this;
590     }
591 
592     //-----------------------------------------------------------------------
593     /**
594      * Checks if this time-zone ID is equal to another time-zone ID.
595      * <p>
596      * The comparison is based on the ID.
597      *
598      * @param obj  the object to check, null returns false
599      * @return true if this is equal to the other time-zone ID
600      */
601     @Override
602     public boolean equals(Object obj) {
603         if (this == obj) {
604            return true;
605         }
606         if (obj instanceof ZoneId) {
607             ZoneId other = (ZoneId) obj;
608             return getId().equals(other.getId());
609         }
610         return false;
611     }
612 
613     /**
614      * A hash code for this time-zone ID.
615      *
616      * @return a suitable hash code
617      */
618     @Override
619     public int hashCode() {
620         return getId().hashCode();
621     }
622 
623     //-----------------------------------------------------------------------
624     /**
625      * Defend against malicious streams.
626      *
627      * @throws InvalidObjectException always
628      */
629     private void readObject(ObjectInputStream s) throws InvalidObjectException {
630         throw new InvalidObjectException("Deserialization via serialization delegate");
631     }
632 
633     /**
634      * Outputs this zone as a {@code String}, using the ID.
635      *
636      * @return a string representation of this time-zone ID, not null
637      */
638     @Override
639     public String toString() {
640         return getId();
641     }
642 
643     //-----------------------------------------------------------------------
644     /**
645      * Writes the object using a
646      * <a href="../../serialized-form.html#java.time.Ser">dedicated serialized form</a>.
647      * @serialData
648      * <pre>
649      *  out.writeByte(7);  // identifies a ZoneId (not ZoneOffset)
650      *  out.writeUTF(getId());
651      * </pre>
652      * <p>
653      * When read back in, the {@code ZoneId} will be created as though using
654      * {@link #of(String)}, but without any exception in the case where the
655      * ID has a valid format, but is not in the known set of region-based IDs.
656      *
657      * @return the instance of {@code Ser}, not null
658      */
659     // this is here for serialization Javadoc
660     private Object writeReplace() {
661         return new Ser(Ser.ZONE_REGION_TYPE, this);
662     }
663 
664     abstract void write(DataOutput out) throws IOException;
665 
666 }