129 * instant by obtaining the offset has the potential to be complicated.
130 * <p>
131 * For Gaps, the general strategy is that if the local date-time falls in the
132 * middle of a Gap, then the resulting zoned date-time will have a local date-time
133 * shifted forwards by the length of the Gap, resulting in a date-time in the later
134 * offset, typically "summer" time.
135 * <p>
136 * For Overlaps, the general strategy is that if the local date-time falls in the
137 * middle of an Overlap, then the previous offset will be retained. If there is no
138 * previous offset, or the previous offset is invalid, then the earlier offset is
139 * used, typically "summer" time. Two additional methods,
140 * {@link #withEarlierOffsetAtOverlap()} and {@link #withLaterOffsetAtOverlap()},
141 * help manage the case of an overlap.
142 * <p>
143 * In terms of design, this class should be viewed primarily as the combination
144 * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
145 * a vital, but secondary, piece of information, used to ensure that the class
146 * represents an instant, especially during a daylight savings overlap.
147 * <p>
148 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
149 * class; programmers should treat instances that are
150 * {@linkplain #equals(Object) equal} as interchangeable and should not
151 * use instances for synchronization, or unpredictable behavior may
152 * occur. For example, in a future release, synchronization may fail.
153 * The {@code equals} method should be used for comparisons.
154 *
155 * @implSpec
156 * A {@code ZonedDateTime} holds state equivalent to three separate objects,
157 * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.
158 * The offset and local date-time are used to define an instant when necessary.
159 * The zone ID is used to obtain the rules for how and when the offset changes.
160 * The offset cannot be freely set, as the zone controls which offsets are valid.
161 * <p>
162 * This class is immutable and thread-safe.
163 *
164 * @since 1.8
165 */
166 @jdk.internal.ValueBased
167 public final class ZonedDateTime
168 implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {
169
170 /**
171 * Serialization version.
172 */
173 @java.io.Serial
174 private static final long serialVersionUID = -6260982410461394882L;
175
176 /**
177 * @serial The local date-time.
178 */
179 private final LocalDateTime dateTime;
180 /**
181 * @serial The offset from UTC/Greenwich.
182 */
183 private final ZoneOffset offset;
184 /**
185 * @serial The time-zone.
186 */
2244 * out.writeByte(6); // identifies a ZonedDateTime
2245 * // the <a href="{@docRoot}/serialized-form.html#java.time.LocalDateTime">dateTime</a> excluding the one byte header
2246 * // the <a href="{@docRoot}/serialized-form.html#java.time.ZoneOffset">offset</a> excluding the one byte header
2247 * // the <a href="{@docRoot}/serialized-form.html#java.time.ZoneId">zone ID</a> excluding the one byte header
2248 * </pre>
2249 *
2250 * @return the instance of {@code Ser}, not null
2251 */
2252 @java.io.Serial
2253 private Object writeReplace() {
2254 return new Ser(Ser.ZONE_DATE_TIME_TYPE, this);
2255 }
2256
2257 /**
2258 * Defend against malicious streams.
2259 *
2260 * @param s the stream to read
2261 * @throws InvalidObjectException always
2262 */
2263 @java.io.Serial
2264 private void readObject(ObjectInputStream s) throws InvalidObjectException {
2265 throw new InvalidObjectException("Deserialization via serialization delegate");
2266 }
2267
2268 void writeExternal(DataOutput out) throws IOException {
2269 dateTime.writeExternal(out);
2270 offset.writeExternal(out);
2271 zone.write(out);
2272 }
2273
2274 static ZonedDateTime readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
2275 LocalDateTime dateTime = LocalDateTime.readExternal(in);
2276 ZoneOffset offset = ZoneOffset.readExternal(in);
2277 ZoneId zone = (ZoneId) Ser.read(in);
2278 return ZonedDateTime.ofLenient(dateTime, offset, zone);
2279 }
2280
2281 }
|
129 * instant by obtaining the offset has the potential to be complicated.
130 * <p>
131 * For Gaps, the general strategy is that if the local date-time falls in the
132 * middle of a Gap, then the resulting zoned date-time will have a local date-time
133 * shifted forwards by the length of the Gap, resulting in a date-time in the later
134 * offset, typically "summer" time.
135 * <p>
136 * For Overlaps, the general strategy is that if the local date-time falls in the
137 * middle of an Overlap, then the previous offset will be retained. If there is no
138 * previous offset, or the previous offset is invalid, then the earlier offset is
139 * used, typically "summer" time. Two additional methods,
140 * {@link #withEarlierOffsetAtOverlap()} and {@link #withLaterOffsetAtOverlap()},
141 * help manage the case of an overlap.
142 * <p>
143 * In terms of design, this class should be viewed primarily as the combination
144 * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
145 * a vital, but secondary, piece of information, used to ensure that the class
146 * represents an instant, especially during a daylight savings overlap.
147 * <p>
148 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
149 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
150 * as interchangeable and should not use instances for synchronization, mutexes, or
151 * with {@linkplain java.lang.ref.Reference object references}.
152 *
153 * <div class="preview-block">
154 * <div class="preview-comment">
155 * When preview features are enabled, {@code ZonedDateTime} is a {@linkplain Class#isValue value class}.
156 * Use of value class instances for synchronization, mutexes, or with
157 * {@linkplain java.lang.ref.Reference object references} result in
158 * {@link IdentityException}.
159 * </div>
160 * </div>
161 *
162 * @implSpec
163 * A {@code ZonedDateTime} holds state equivalent to three separate objects,
164 * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.
165 * The offset and local date-time are used to define an instant when necessary.
166 * The zone ID is used to obtain the rules for how and when the offset changes.
167 * The offset cannot be freely set, as the zone controls which offsets are valid.
168 * <p>
169 * This class is immutable and thread-safe.
170 *
171 * @since 1.8
172 */
173 @jdk.internal.ValueBased
174 @jdk.internal.MigratedValueClass
175 public final class ZonedDateTime
176 implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {
177
178 /**
179 * Serialization version.
180 */
181 @java.io.Serial
182 private static final long serialVersionUID = -6260982410461394882L;
183
184 /**
185 * @serial The local date-time.
186 */
187 private final LocalDateTime dateTime;
188 /**
189 * @serial The offset from UTC/Greenwich.
190 */
191 private final ZoneOffset offset;
192 /**
193 * @serial The time-zone.
194 */
2252 * out.writeByte(6); // identifies a ZonedDateTime
2253 * // the <a href="{@docRoot}/serialized-form.html#java.time.LocalDateTime">dateTime</a> excluding the one byte header
2254 * // the <a href="{@docRoot}/serialized-form.html#java.time.ZoneOffset">offset</a> excluding the one byte header
2255 * // the <a href="{@docRoot}/serialized-form.html#java.time.ZoneId">zone ID</a> excluding the one byte header
2256 * </pre>
2257 *
2258 * @return the instance of {@code Ser}, not null
2259 */
2260 @java.io.Serial
2261 private Object writeReplace() {
2262 return new Ser(Ser.ZONE_DATE_TIME_TYPE, this);
2263 }
2264
2265 /**
2266 * Defend against malicious streams.
2267 *
2268 * @param s the stream to read
2269 * @throws InvalidObjectException always
2270 */
2271 @java.io.Serial
2272 @SuppressWarnings("serial") // this method is not invoked for value classes
2273 private void readObject(ObjectInputStream s) throws InvalidObjectException {
2274 throw new InvalidObjectException("Deserialization via serialization delegate");
2275 }
2276
2277 void writeExternal(DataOutput out) throws IOException {
2278 dateTime.writeExternal(out);
2279 offset.writeExternal(out);
2280 zone.write(out);
2281 }
2282
2283 static ZonedDateTime readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
2284 LocalDateTime dateTime = LocalDateTime.readExternal(in);
2285 ZoneOffset offset = ZoneOffset.readExternal(in);
2286 ZoneId zone = (ZoneId) Ser.read(in);
2287 return ZonedDateTime.ofLenient(dateTime, offset, zone);
2288 }
2289
2290 }
|