178 * proleptically, which is equivalent to the (mean) solar time on the
179 * prime meridian (Greenwich). In this segment, the Java Time-Scale is
180 * identical to the consensus international time scale. The exact
181 * boundary between the two segments is the instant where UT1 = UTC
182 * between 1972-11-03T00:00 and 1972-11-04T12:00.
183 * <p>
184 * Implementations of the Java time-scale using the JSR-310 API are not
185 * required to provide any clock that is sub-second accurate, or that
186 * progresses monotonically or smoothly. Implementations are therefore
187 * not required to actually perform the UTC-SLS slew or to otherwise be
188 * aware of leap seconds. JSR-310 does, however, require that
189 * implementations must document the approach they use when defining a
190 * clock representing the current instant.
191 * See {@link Clock} for details on the available clocks.
192 * <p>
193 * The Java time-scale is used for all date-time classes.
194 * This includes {@code Instant}, {@code LocalDate}, {@code LocalTime}, {@code OffsetDateTime},
195 * {@code ZonedDateTime} and {@code Duration}.
196 * <p>
197 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
198 * class; programmers should treat instances that are
199 * {@linkplain #equals(Object) equal} as interchangeable and should not
200 * use instances for synchronization, or unpredictable behavior may
201 * occur. For example, in a future release, synchronization may fail.
202 * The {@code equals} method should be used for comparisons.
203 *
204 * @implSpec
205 * This class is immutable and thread-safe.
206 *
207 * @since 1.8
208 */
209 @jdk.internal.ValueBased
210 public final class Instant
211 implements Temporal, TemporalAdjuster, Comparable<Instant>, Serializable {
212
213 /**
214 * Constant for the 1970-01-01T00:00:00Z epoch instant.
215 */
216 public static final Instant EPOCH = new Instant(0, 0);
217 /**
218 * The minimum supported epoch second.
219 */
220 private static final long MIN_SECOND = -31557014167219200L;
221 /**
222 * The maximum supported epoch second.
223 */
224 private static final long MAX_SECOND = 31556889864403199L;
225 /**
226 * The minimum supported {@code Instant}, '-1000000000-01-01T00:00Z'.
227 * This could be used by an application as a "far past" instant.
228 * <p>
229 * This is one year earlier than the minimum {@code LocalDateTime}.
|
178 * proleptically, which is equivalent to the (mean) solar time on the
179 * prime meridian (Greenwich). In this segment, the Java Time-Scale is
180 * identical to the consensus international time scale. The exact
181 * boundary between the two segments is the instant where UT1 = UTC
182 * between 1972-11-03T00:00 and 1972-11-04T12:00.
183 * <p>
184 * Implementations of the Java time-scale using the JSR-310 API are not
185 * required to provide any clock that is sub-second accurate, or that
186 * progresses monotonically or smoothly. Implementations are therefore
187 * not required to actually perform the UTC-SLS slew or to otherwise be
188 * aware of leap seconds. JSR-310 does, however, require that
189 * implementations must document the approach they use when defining a
190 * clock representing the current instant.
191 * See {@link Clock} for details on the available clocks.
192 * <p>
193 * The Java time-scale is used for all date-time classes.
194 * This includes {@code Instant}, {@code LocalDate}, {@code LocalTime}, {@code OffsetDateTime},
195 * {@code ZonedDateTime} and {@code Duration}.
196 * <p>
197 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
198 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
199 * as interchangeable and should not use instances for synchronization, mutexes, or
200 * with {@linkplain java.lang.ref.Reference object references}.
201 *
202 * <div class="preview-block">
203 * <div class="preview-comment">
204 * When preview features are enabled, {@code Instant} is a {@linkplain Class#isValue value class}.
205 * Use of value class instances for synchronization, mutexes, or with
206 * {@linkplain java.lang.ref.Reference object references} result in
207 * {@link IdentityException}.
208 * </div>
209 * </div>
210 *
211 * @implSpec
212 * This class is immutable and thread-safe.
213 *
214 * @since 1.8
215 */
216 @jdk.internal.ValueBased
217 @jdk.internal.MigratedValueClass
218 public final class Instant
219 implements Temporal, TemporalAdjuster, Comparable<Instant>, Serializable {
220
221 /**
222 * Constant for the 1970-01-01T00:00:00Z epoch instant.
223 */
224 public static final Instant EPOCH = new Instant(0, 0);
225 /**
226 * The minimum supported epoch second.
227 */
228 private static final long MIN_SECOND = -31557014167219200L;
229 /**
230 * The maximum supported epoch second.
231 */
232 private static final long MAX_SECOND = 31556889864403199L;
233 /**
234 * The minimum supported {@code Instant}, '-1000000000-01-01T00:00Z'.
235 * This could be used by an application as a "far past" instant.
236 * <p>
237 * This is one year earlier than the minimum {@code LocalDateTime}.
|