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 *
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 }
|
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, mutexes, 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, mutexes, 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 @jdk.internal.MigratedValueClass
142 public final class Duration
143 implements TemporalAmount, Comparable<Duration>, Serializable {
144
145 /**
146 * Constant for a duration of zero.
147 */
148 public static final Duration ZERO = new Duration(0, 0);
149 /**
150 * The minimum supported {@code Duration}, which is {@link Long#MIN_VALUE}
151 * seconds.
152 *
153 * @apiNote This constant represents the smallest possible instance of
154 * {@code Duration}. Since {@code Duration} is directed, the smallest
155 * possible duration is negative.
156 *
157 * The constant is intended to be used as a sentinel value or in tests.
158 * Care should be taken when performing arithmetic on {@code MIN} as there
159 * is a high risk that {@link ArithmeticException} or {@link DateTimeException}
160 * will be thrown.
161 *
1581 * <pre>
1582 * out.writeByte(1); // identifies a Duration
1583 * out.writeLong(seconds);
1584 * out.writeInt(nanos);
1585 * </pre>
1586 *
1587 * @return the instance of {@code Ser}, not null
1588 */
1589 @java.io.Serial
1590 private Object writeReplace() {
1591 return new Ser(Ser.DURATION_TYPE, this);
1592 }
1593
1594 /**
1595 * Defend against malicious streams.
1596 *
1597 * @param s the stream to read
1598 * @throws InvalidObjectException always
1599 */
1600 @java.io.Serial
1601 @SuppressWarnings("serial") // this method is not invoked for value classes
1602 private void readObject(ObjectInputStream s) throws InvalidObjectException {
1603 throw new InvalidObjectException("Deserialization via serialization delegate");
1604 }
1605
1606 void writeExternal(DataOutput out) throws IOException {
1607 out.writeLong(seconds);
1608 out.writeInt(nanos);
1609 }
1610
1611 static Duration readExternal(DataInput in) throws IOException {
1612 long seconds = in.readLong();
1613 int nanos = in.readInt();
1614 return Duration.ofSeconds(seconds, nanos);
1615 }
1616
1617 }
|