1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.lang3.time;
19
20 import java.time.Instant;
21
22 /**
23 * Works with {@link Instant}s.
24 *
25 * @since 3.21.0
26 */
27 public class Instants {
28
29 private static long toBound(final Instant instant, final long negBound, final long posBound) {
30 return instant.getEpochSecond() < 0 ? negBound : posBound;
31 }
32
33 /**
34 * Converts an Instant to milliseconds bound to a {@code long} without throwing {@link ArithmeticException}.
35 * <ul>
36 * <li>If the duration milliseconds are greater than {@link Long#MAX_VALUE}, then return {@link Long#MAX_VALUE}.</li>
37 * <li>If the duration milliseconds are lesser than {@link Long#MIN_VALUE}, then return {@link Long#MIN_VALUE}.</li>
38 * <li>If the instant is null, treat it as {@link Instant#EPOCH}.</li>
39 * </ul>
40 *
41 * @param instant The instant to convert, not null.
42 * @return long The given Instant in milliseconds.
43 * @see Instant#toEpochMilli()
44 * @see Long#MIN_VALUE
45 * @see Long#MAX_VALUE
46 */
47 public static long toEpochMillis(final Instant instant) {
48 final Instant instant2 = toInstant(instant);
49 try {
50 return instant2.toEpochMilli();
51 } catch (final ArithmeticException e) {
52 return toBound(instant2, Long.MIN_VALUE, Long.MAX_VALUE);
53 }
54 }
55
56 /**
57 * Returns the given non-null instant, or {@link Instant#EPOCH} if null.
58 *
59 * @param instant The instant to test, may be null.
60 * @return The given non-null instant, or {@link Instant#EPOCH} if null.
61 */
62 public static Instant toInstant(final Instant instant) {
63 return toInstant(instant, Instant.EPOCH);
64 }
65
66 /**
67 * Returns the given non-null instant, or {@code defaultInstant} if instant is null.
68 *
69 * @param instant The instant to test, may be null.
70 * @param defaultInstant The default instant to use if the given instant is null, may be null.
71 * @return The given non-null instant, or {@code defaultInstant} if null.
72 */
73 public static Instant toInstant(final Instant instant, final Instant defaultInstant) {
74 return instant != null ? instant : defaultInstant;
75 }
76
77 /**
78 * Converts an Instant to milliseconds since that Instant bound to a {@code long} without throwing {@link ArithmeticException}.
79 * <ul>
80 * <li>If the duration milliseconds are greater than {@link Long#MAX_VALUE}, then return {@link Long#MAX_VALUE}.</li>
81 * <li>If the duration milliseconds are lesser than {@link Long#MIN_VALUE}, then return {@link Long#MIN_VALUE}.</li>
82 * <li>If the instant is null, treat it as {@link Instant#EPOCH}.</li>
83 * </ul>
84 *
85 * @param instant The instant to convert, not null.
86 * @return long The duration in milliseconds since the given Instant.
87 */
88 public static long toMillisSince(final Instant instant) {
89 return DurationUtils.toMillisLong(DurationUtils.since(toInstant(instant)));
90 }
91
92 /**
93 * No instances needed.
94 */
95 private Instants() {
96 // empty.
97 }
98 }