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 */
187 private final ZoneId zone;
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 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 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 public final /*value*/ class ZonedDateTime
175 implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {
176
177 /**
178 * Serialization version.
179 */
180 @java.io.Serial
181 private static final long serialVersionUID = -6260982410461394882L;
182
183 /**
184 * @serial The local date-time.
185 */
186 private final LocalDateTime dateTime;
187 /**
188 * @serial The offset from UTC/Greenwich.
189 */
190 private final ZoneOffset offset;
191 /**
192 * @serial The time-zone.
193 */
194 private final ZoneId zone;
2251 * out.writeByte(6); // identifies a ZonedDateTime
2252 * // the <a href="{@docRoot}/serialized-form.html#java.time.LocalDateTime">dateTime</a> excluding the one byte header
2253 * // the <a href="{@docRoot}/serialized-form.html#java.time.ZoneOffset">offset</a> excluding the one byte header
2254 * // the <a href="{@docRoot}/serialized-form.html#java.time.ZoneId">zone ID</a> excluding the one byte header
2255 * </pre>
2256 *
2257 * @return the instance of {@code Ser}, not null
2258 */
2259 @java.io.Serial
2260 private Object writeReplace() {
2261 return new Ser(Ser.ZONE_DATE_TIME_TYPE, this);
2262 }
2263
2264 /**
2265 * Defend against malicious streams.
2266 *
2267 * @param s the stream to read
2268 * @throws InvalidObjectException always
2269 */
2270 @java.io.Serial
2271 @SuppressWarnings("serial") // this method is not invoked for value classes
2272 private void readObject(ObjectInputStream s) throws InvalidObjectException {
2273 throw new InvalidObjectException("Deserialization via serialization delegate");
2274 }
2275
2276 void writeExternal(DataOutput out) throws IOException {
2277 dateTime.writeExternal(out);
2278 offset.writeExternal(out);
2279 zone.write(out);
2280 }
2281
2282 static ZonedDateTime readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
2283 LocalDateTime dateTime = LocalDateTime.readExternal(in);
2284 ZoneOffset offset = ZoneOffset.readExternal(in);
2285 ZoneId zone = (ZoneId) Ser.read(in);
2286 return ZonedDateTime.ofLenient(dateTime, offset, zone);
2287 }
2288
2289 }
|