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}.
1413 * <pre>
1414 * out.writeByte(2); // identifies an Instant
1415 * out.writeLong(seconds);
1416 * out.writeInt(nanos);
1417 * </pre>
1418 *
1419 * @return the instance of {@code Ser}, not null
1420 */
1421 @java.io.Serial
1422 private Object writeReplace() {
1423 return new Ser(Ser.INSTANT_TYPE, this);
1424 }
1425
1426 /**
1427 * Defend against malicious streams.
1428 *
1429 * @param s the stream to read
1430 * @throws InvalidObjectException always
1431 */
1432 @java.io.Serial
1433 private void readObject(ObjectInputStream s) throws InvalidObjectException {
1434 throw new InvalidObjectException("Deserialization via serialization delegate");
1435 }
1436
1437 void writeExternal(DataOutput out) throws IOException {
1438 out.writeLong(seconds);
1439 out.writeInt(nanos);
1440 }
1441
1442 static Instant readExternal(DataInput in) throws IOException {
1443 long seconds = in.readLong();
1444 int nanos = in.readInt();
1445 return Instant.ofEpochSecond(seconds, nanos);
1446 }
1447
1448 }
|
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}.
1421 * <pre>
1422 * out.writeByte(2); // identifies an Instant
1423 * out.writeLong(seconds);
1424 * out.writeInt(nanos);
1425 * </pre>
1426 *
1427 * @return the instance of {@code Ser}, not null
1428 */
1429 @java.io.Serial
1430 private Object writeReplace() {
1431 return new Ser(Ser.INSTANT_TYPE, this);
1432 }
1433
1434 /**
1435 * Defend against malicious streams.
1436 *
1437 * @param s the stream to read
1438 * @throws InvalidObjectException always
1439 */
1440 @java.io.Serial
1441 @SuppressWarnings("serial") // this method is not invoked for value classes
1442 private void readObject(ObjectInputStream s) throws InvalidObjectException {
1443 throw new InvalidObjectException("Deserialization via serialization delegate");
1444 }
1445
1446 void writeExternal(DataOutput out) throws IOException {
1447 out.writeLong(seconds);
1448 out.writeInt(nanos);
1449 }
1450
1451 static Instant readExternal(DataInput in) throws IOException {
1452 long seconds = in.readLong();
1453 int nanos = in.readInt();
1454 return Instant.ofEpochSecond(seconds, nanos);
1455 }
1456
1457 }
|