127 * instant by obtaining the offset has the potential to be complicated.
128 * <p>
129 * For Gaps, the general strategy is that if the local date-time falls in the
130 * middle of a Gap, then the resulting zoned date-time will have a local date-time
131 * shifted forwards by the length of the Gap, resulting in a date-time in the later
132 * offset, typically "summer" time.
133 * <p>
134 * For Overlaps, the general strategy is that if the local date-time falls in the
135 * middle of an Overlap, then the previous offset will be retained. If there is no
136 * previous offset, or the previous offset is invalid, then the earlier offset is
137 * used, typically "summer" time.. Two additional methods,
138 * {@link #withEarlierOffsetAtOverlap()} and {@link #withLaterOffsetAtOverlap()},
139 * help manage the case of an overlap.
140 * <p>
141 * In terms of design, this class should be viewed primarily as the combination
142 * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
143 * a vital, but secondary, piece of information, used to ensure that the class
144 * represents an instant, especially during a daylight savings overlap.
145 * <p>
146 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
147 * class; programmers should treat instances that are
148 * {@linkplain #equals(Object) equal} as interchangeable and should not
149 * use instances for synchronization, or unpredictable behavior may
150 * occur. For example, in a future release, synchronization may fail.
151 * The {@code equals} method should be used for comparisons.
152 *
153 * @implSpec
154 * A {@code ZonedDateTime} holds state equivalent to three separate objects,
155 * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.
156 * The offset and local date-time are used to define an instant when necessary.
157 * The zone ID is used to obtain the rules for how and when the offset changes.
158 * The offset cannot be freely set, as the zone controls which offsets are valid.
159 * <p>
160 * This class is immutable and thread-safe.
161 *
162 * @since 1.8
163 */
164 @jdk.internal.ValueBased
165 public final class ZonedDateTime
166 implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {
167
168 /**
169 * Serialization version.
170 */
171 @java.io.Serial
172 private static final long serialVersionUID = -6260982410461394882L;
173
174 /**
175 * The local date-time.
176 */
177 private final LocalDateTime dateTime;
178 /**
179 * The offset from UTC/Greenwich.
180 */
181 private final ZoneOffset offset;
182 /**
183 * The time-zone.
184 */
|
127 * instant by obtaining the offset has the potential to be complicated.
128 * <p>
129 * For Gaps, the general strategy is that if the local date-time falls in the
130 * middle of a Gap, then the resulting zoned date-time will have a local date-time
131 * shifted forwards by the length of the Gap, resulting in a date-time in the later
132 * offset, typically "summer" time.
133 * <p>
134 * For Overlaps, the general strategy is that if the local date-time falls in the
135 * middle of an Overlap, then the previous offset will be retained. If there is no
136 * previous offset, or the previous offset is invalid, then the earlier offset is
137 * used, typically "summer" time.. Two additional methods,
138 * {@link #withEarlierOffsetAtOverlap()} and {@link #withLaterOffsetAtOverlap()},
139 * help manage the case of an overlap.
140 * <p>
141 * In terms of design, this class should be viewed primarily as the combination
142 * of a {@code LocalDateTime} and a {@code ZoneId}. The {@code ZoneOffset} is
143 * a vital, but secondary, piece of information, used to ensure that the class
144 * represents an instant, especially during a daylight savings overlap.
145 * <p>
146 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
147 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
148 * as interchangeable and should not use instances for synchronization, mutexes, or
149 * with {@linkplain java.lang.ref.Reference object references}.
150 *
151 * <div class="preview-block">
152 * <div class="preview-comment">
153 * When preview features are enabled, {@code ZonedDateTime} is a {@linkplain Class#isValue value class}.
154 * Use of value class instances for synchronization, mutexes, or with
155 * {@linkplain java.lang.ref.Reference object references} result in
156 * {@link IdentityException}.
157 * </div>
158 * </div>
159 *
160 * @implSpec
161 * A {@code ZonedDateTime} holds state equivalent to three separate objects,
162 * a {@code LocalDateTime}, a {@code ZoneId} and the resolved {@code ZoneOffset}.
163 * The offset and local date-time are used to define an instant when necessary.
164 * The zone ID is used to obtain the rules for how and when the offset changes.
165 * The offset cannot be freely set, as the zone controls which offsets are valid.
166 * <p>
167 * This class is immutable and thread-safe.
168 *
169 * @since 1.8
170 */
171 @jdk.internal.ValueBased
172 @jdk.internal.MigratedValueClass
173 public final class ZonedDateTime
174 implements Temporal, ChronoZonedDateTime<LocalDate>, Serializable {
175
176 /**
177 * Serialization version.
178 */
179 @java.io.Serial
180 private static final long serialVersionUID = -6260982410461394882L;
181
182 /**
183 * The local date-time.
184 */
185 private final LocalDateTime dateTime;
186 /**
187 * The offset from UTC/Greenwich.
188 */
189 private final ZoneOffset offset;
190 /**
191 * The time-zone.
192 */
|