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
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
166 * {@linkplain #equals(Object) equal} as interchangeable and should not
167 * use instances for synchronization, or unpredictable behavior may
168 * occur. For example, in a future release, synchronization may fail.
169 * The {@code equals} method should be used for comparisons.
170 *
171 * @implSpec
172 * This abstract sealed class permits two implementations, both of which are immutable and
173 * thread-safe. One implementation models region-based IDs, the other is {@code ZoneOffset}
174 * modelling offset-based IDs. This difference is visible in serialization.
175 *
176 * @since 1.8
177 * @sealedGraph
178 */
179 @jdk.internal.ValueBased
180 public abstract sealed class ZoneId implements Serializable permits ZoneOffset, ZoneRegion {
181
182 /**
183 * A map of zone overrides to enable the short time-zone names to be used.
184 * <p>
185 * Use of short zone IDs has been deprecated in {@code java.util.TimeZone}.
186 * This map allows the IDs to continue to be used via the
187 * {@link #of(String, Map)} factory method.
188 * <p>
189 * This map contains a mapping of the IDs that is in line with TZDB 2024b and
|
1 /*
2 * Copyright (c) 2012, 2026, 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
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 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
|