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
102 * exactly equal to 24 hours, thus ignoring daylight savings effects.
103 * See {@link Period} for the date-based equivalent to this class.
104 * <p>
105 * A physical duration could be of infinite length.
106 * For practicality, the duration is stored with constraints similar to {@link Instant}.
107 * The duration uses nanosecond resolution with a maximum value of the seconds that can
108 * be held in a {@code long}. This is greater than the current estimated age of the universe.
109 * <p>
110 * The range of a duration requires the storage of a number larger than a {@code long}.
111 * To achieve this, the class stores a {@code long} representing seconds and an {@code int}
112 * representing nanosecond-of-second, which will always be between 0 and 999,999,999.
113 * The model is of a directed duration, meaning that the duration may be negative.
114 * <p>
115 * The duration is measured in "seconds", but these are not necessarily identical to
116 * the scientific "SI second" definition based on atomic clocks.
117 * This difference only impacts durations measured near a leap-second and should not affect
118 * most applications.
119 * See {@link Instant} for a discussion as to the meaning of the second and time-scales.
120 * <p>
121 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
122 * class; programmers should treat instances that are
123 * {@linkplain #equals(Object) equal} as interchangeable and should not
124 * use instances for synchronization, or unpredictable behavior may
125 * occur. For example, in a future release, synchronization may fail.
126 * The {@code equals} method should be used for comparisons.
127 *
128 * @implSpec
129 * This class is immutable and thread-safe.
130 *
131 * @since 1.8
132 */
133 @jdk.internal.ValueBased
134 public final class Duration
135 implements TemporalAmount, Comparable<Duration>, Serializable {
136
137 /**
138 * Constant for a duration of zero.
139 */
140 public static final Duration ZERO = new Duration(0, 0);
141 /**
142 * The minimum supported {@code Duration}, which is {@link Long#MIN_VALUE}
143 * seconds.
144 *
145 * @apiNote This constant represents the smallest possible instance of
146 * {@code Duration}. Since {@code Duration} is directed, the smallest
147 * possible duration is negative.
148 *
149 * The constant is intended to be used as a sentinel value or in tests.
150 * Care should be taken when performing arithmetic on {@code MIN} as there
151 * is a high risk that {@link ArithmeticException} or {@link DateTimeException}
152 * will be thrown.
153 *
154 * @since 26
1573 * <pre>
1574 * out.writeByte(1); // identifies a Duration
1575 * out.writeLong(seconds);
1576 * out.writeInt(nanos);
1577 * </pre>
1578 *
1579 * @return the instance of {@code Ser}, not null
1580 */
1581 @java.io.Serial
1582 private Object writeReplace() {
1583 return new Ser(Ser.DURATION_TYPE, this);
1584 }
1585
1586 /**
1587 * Defend against malicious streams.
1588 *
1589 * @param s the stream to read
1590 * @throws InvalidObjectException always
1591 */
1592 @java.io.Serial
1593 private void readObject(ObjectInputStream s) throws InvalidObjectException {
1594 throw new InvalidObjectException("Deserialization via serialization delegate");
1595 }
1596
1597 void writeExternal(DataOutput out) throws IOException {
1598 out.writeLong(seconds);
1599 out.writeInt(nanos);
1600 }
1601
1602 static Duration readExternal(DataInput in) throws IOException {
1603 long seconds = in.readLong();
1604 int nanos = in.readInt();
1605 return Duration.ofSeconds(seconds, nanos);
1606 }
1607
1608 }
|
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
102 * exactly equal to 24 hours, thus ignoring daylight savings effects.
103 * See {@link Period} for the date-based equivalent to this class.
104 * <p>
105 * A physical duration could be of infinite length.
106 * For practicality, the duration is stored with constraints similar to {@link Instant}.
107 * The duration uses nanosecond resolution with a maximum value of the seconds that can
108 * be held in a {@code long}. This is greater than the current estimated age of the universe.
109 * <p>
110 * The range of a duration requires the storage of a number larger than a {@code long}.
111 * To achieve this, the class stores a {@code long} representing seconds and an {@code int}
112 * representing nanosecond-of-second, which will always be between 0 and 999,999,999.
113 * The model is of a directed duration, meaning that the duration may be negative.
114 * <p>
115 * The duration is measured in "seconds", but these are not necessarily identical to
116 * the scientific "SI second" definition based on atomic clocks.
117 * This difference only impacts durations measured near a leap-second and should not affect
118 * most applications.
119 * See {@link Instant} for a discussion as to the meaning of the second and time-scales.
120 * <p>
121 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
122 * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
123 * as interchangeable and should not use instances for synchronization or
124 * with {@linkplain java.lang.ref.Reference object references}.
125 *
126 * <div class="preview-block">
127 * <div class="preview-comment">
128 * When preview features are enabled, {@code Duration} is a {@linkplain Class#isValue value class}.
129 * Use of value class instances for synchronization or with
130 * {@linkplain java.lang.ref.Reference object references} result in
131 * {@link IdentityException}.
132 * </div>
133 * </div>
134 *
135 * @implSpec
136 * This class is immutable and thread-safe.
137 *
138 * @since 1.8
139 */
140 @jdk.internal.ValueBased
141 public final /*value*/ class Duration
142 implements TemporalAmount, Comparable<Duration>, Serializable {
143
144 /**
145 * Constant for a duration of zero.
146 */
147 public static final Duration ZERO = new Duration(0, 0);
148 /**
149 * The minimum supported {@code Duration}, which is {@link Long#MIN_VALUE}
150 * seconds.
151 *
152 * @apiNote This constant represents the smallest possible instance of
153 * {@code Duration}. Since {@code Duration} is directed, the smallest
154 * possible duration is negative.
155 *
156 * The constant is intended to be used as a sentinel value or in tests.
157 * Care should be taken when performing arithmetic on {@code MIN} as there
158 * is a high risk that {@link ArithmeticException} or {@link DateTimeException}
159 * will be thrown.
160 *
161 * @since 26
1580 * <pre>
1581 * out.writeByte(1); // identifies a Duration
1582 * out.writeLong(seconds);
1583 * out.writeInt(nanos);
1584 * </pre>
1585 *
1586 * @return the instance of {@code Ser}, not null
1587 */
1588 @java.io.Serial
1589 private Object writeReplace() {
1590 return new Ser(Ser.DURATION_TYPE, this);
1591 }
1592
1593 /**
1594 * Defend against malicious streams.
1595 *
1596 * @param s the stream to read
1597 * @throws InvalidObjectException always
1598 */
1599 @java.io.Serial
1600 @SuppressWarnings("serial") // this method is not invoked for value classes
1601 private void readObject(ObjectInputStream s) throws InvalidObjectException {
1602 throw new InvalidObjectException("Deserialization via serialization delegate");
1603 }
1604
1605 void writeExternal(DataOutput out) throws IOException {
1606 out.writeLong(seconds);
1607 out.writeInt(nanos);
1608 }
1609
1610 static Duration readExternal(DataInput in) throws IOException {
1611 long seconds = in.readLong();
1612 int nanos = in.readInt();
1613 return Duration.ofSeconds(seconds, nanos);
1614 }
1615
1616 }
|