1 /*
2 * Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
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}.
230 * This provides sufficient values to handle the range of {@code ZoneOffset}
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 }
|
1 /*
2 * Copyright (c) 2012, 2026, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
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 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 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 public final /*value*/ class Instant
218 implements Temporal, TemporalAdjuster, Comparable<Instant>, Serializable {
219
220 /**
221 * Constant for the 1970-01-01T00:00:00Z epoch instant.
222 */
223 public static final Instant EPOCH = new Instant(0, 0);
224 /**
225 * The minimum supported epoch second.
226 */
227 private static final long MIN_SECOND = -31557014167219200L;
228 /**
229 * The maximum supported epoch second.
230 */
231 private static final long MAX_SECOND = 31556889864403199L;
232 /**
233 * The minimum supported {@code Instant}, '-1000000000-01-01T00:00Z'.
234 * This could be used by an application as a "far past" instant.
235 * <p>
236 * This is one year earlier than the minimum {@code LocalDateTime}.
237 * This provides sufficient values to handle the range of {@code ZoneOffset}
1420 * <pre>
1421 * out.writeByte(2); // identifies an Instant
1422 * out.writeLong(seconds);
1423 * out.writeInt(nanos);
1424 * </pre>
1425 *
1426 * @return the instance of {@code Ser}, not null
1427 */
1428 @java.io.Serial
1429 private Object writeReplace() {
1430 return new Ser(Ser.INSTANT_TYPE, this);
1431 }
1432
1433 /**
1434 * Defend against malicious streams.
1435 *
1436 * @param s the stream to read
1437 * @throws InvalidObjectException always
1438 */
1439 @java.io.Serial
1440 @SuppressWarnings("serial") // this method is not invoked for value classes
1441 private void readObject(ObjectInputStream s) throws InvalidObjectException {
1442 throw new InvalidObjectException("Deserialization via serialization delegate");
1443 }
1444
1445 void writeExternal(DataOutput out) throws IOException {
1446 out.writeLong(seconds);
1447 out.writeInt(nanos);
1448 }
1449
1450 static Instant readExternal(DataInput in) throws IOException {
1451 long seconds = in.readLong();
1452 int nanos = in.readInt();
1453 return Instant.ofEpochSecond(seconds, nanos);
1454 }
1455
1456 }
|