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 */
|
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 */
|