1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * https://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.commons.compress.utils;
20
21 import java.nio.file.attribute.FileTime;
22 import java.time.Instant;
23 import java.util.Date;
24 import java.util.concurrent.TimeUnit;
25
26 import org.apache.commons.io.file.attribute.FileTimes;
27
28 /**
29 * Utility class for handling time-related types and conversions.
30 * <p>
31 * Understanding Unix vs NTFS timestamps:
32 * </p>
33 * <ul>
34 * <li>A <a href="https://en.wikipedia.org/wiki/Unix_time">Unix timestamp</a> is a primitive long starting at the Unix Epoch on January 1st, 1970 at Coordinated
35 * Universal Time (UTC)</li>
36 * <li>An <a href="https://learn.microsoft.com/en-us/windows/win32/sysinfo/file-times">NTFS timestamp</a> is a file time is a 64-bit value that represents the
37 * number of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).</li>
38 * </ul>
39 *
40 * @since 1.23
41 * @see FileTimes
42 * @deprecated Use {@link FileTimes}.
43 */
44 @Deprecated
45 public final class TimeUtils {
46
47 /** The amount of 100-nanosecond intervals in one millisecond. */
48 static final long HUNDRED_NANOS_PER_MILLISECOND = TimeUnit.MILLISECONDS.toNanos(1) / 100;
49
50 /**
51 * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx">Windows File Times</a>
52 * <p>
53 * A file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated
54 * Universal Time (UTC). This is the offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
55 * </p>
56 */
57 static final long WINDOWS_EPOCH_OFFSET = -116444736000000000L;
58
59 /**
60 * Tests whether a FileTime can be safely represented in the standard Unix time.
61 *
62 * @param time the FileTime to evaluate, can be null.
63 * @return true if the time exceeds the minimum or maximum Unix time, false otherwise.
64 * @deprecated use {@link FileTimes#isUnixTime(FileTime)}
65 */
66 @Deprecated
67 public static boolean isUnixTime(final FileTime time) {
68 return FileTimes.isUnixTime(time);
69 }
70
71 /**
72 * Tests whether a given number of seconds (since Epoch) can be safely represented in the standard Unix time.
73 *
74 * @param seconds the number of seconds (since Epoch) to evaluate.
75 * @return true if the time can be represented in the standard Unix time, false otherwise.
76 * @deprecated Use {@link FileTimes#isUnixTime(long)}
77 */
78 @Deprecated
79 public static boolean isUnixTime(final long seconds) {
80 return FileTimes.isUnixTime(seconds);
81 }
82
83 /**
84 * Converts NTFS time (100 nanosecond units since 1 January 1601) to Java time.
85 *
86 * @param ntfsTime the NTFS time in 100 nanosecond units.
87 * @return the Date.
88 * @deprecated Use {@link FileTimes#ntfsTimeToDate(long)}.
89 */
90 @Deprecated
91 public static Date ntfsTimeToDate(final long ntfsTime) {
92 return FileTimes.ntfsTimeToDate(ntfsTime);
93 }
94
95 /**
96 * Converts NTFS time (100-nanosecond units since 1 January 1601) to a FileTime.
97 *
98 * @param ntfsTime the NTFS time in 100-nanosecond units.
99 * @return the FileTime.
100 * @see FileTimes#toNtfsTime(FileTime)
101 * @deprecated Use {@link FileTimes#ntfsTimeToFileTime(long)}.
102 */
103 @Deprecated
104 public static FileTime ntfsTimeToFileTime(final long ntfsTime) {
105 return FileTimes.ntfsTimeToFileTime(ntfsTime);
106 }
107
108 /**
109 * Converts {@link FileTime} to a {@link Date}. If the provided FileTime is {@code null}, the returned Date is also {@code null}.
110 *
111 * @param fileTime the file time to be converted.
112 * @return a {@link Date} which corresponds to the supplied time, or {@code null} if the time is {@code null}.
113 * @see FileTimes#toFileTime(Date)
114 * @deprecated Use {@link FileTimes#toDate(FileTime)}.
115 */
116 @Deprecated
117 public static Date toDate(final FileTime fileTime) {
118 return FileTimes.toDate(fileTime);
119 }
120
121 /**
122 * Converts {@link Date} to a {@link FileTime}. If the provided Date is {@code null}, the returned FileTime is also {@code null}.
123 *
124 * @param date the date to be converted.
125 * @return a {@link FileTime} which corresponds to the supplied date, or {@code null} if the date is {@code null}.
126 * @see FileTimes#toDate(FileTime)
127 * @deprecated Use {@link FileTimes#toFileTime(Date)}.
128 */
129 @Deprecated
130 public static FileTime toFileTime(final Date date) {
131 return FileTimes.toFileTime(date);
132 }
133
134 /**
135 * Converts a {@link Date} to NTFS time.
136 *
137 * @param date the Date.
138 * @return the NTFS time.
139 * @deprecated Use {@link FileTimes#toNtfsTime(Date)}.
140 */
141 @Deprecated
142 public static long toNtfsTime(final Date date) {
143 return FileTimes.toNtfsTime(date);
144 }
145
146 /**
147 * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601).
148 *
149 * @param fileTime the FileTime.
150 * @return the NTFS time in 100-nanosecond units.
151 * @see FileTimes#ntfsTimeToFileTime(long)
152 * @deprecated Use {@link FileTimes#toNtfsTime(FileTime)}.
153 */
154 @Deprecated
155 public static long toNtfsTime(final FileTime fileTime) {
156 return FileTimes.toNtfsTime(fileTime);
157 }
158
159 /**
160 * Converts Java time (milliseconds since Epoch) to NTFS time.
161 *
162 * @param javaTime the Java time.
163 * @return the NTFS time.
164 * @deprecated Use {@link FileTimes#toNtfsTime(long)}
165 */
166 @Deprecated
167 public static long toNtfsTime(final long javaTime) {
168 return FileTimes.toNtfsTime(javaTime);
169 }
170
171 /**
172 * Converts a {@link FileTime} to standard Unix time in seconds.
173 * <p>
174 * The returned seconds value may lie out of bounds of Unix time. Check with {@link FileTimes#isUnixTime(long)}.
175 * </p>
176 *
177 * @param fileTime the original FileTime.
178 * @return the Unix timestamp or 0 if the input is null.
179 * @see FileTimes#isUnixTime(long)
180 * @deprecated Use {@link FileTimes#toUnixTime(FileTime)}.
181 */
182 @Deprecated
183 public static long toUnixTime(final FileTime fileTime) {
184 return FileTimes.toUnixTime(fileTime);
185 }
186
187 /**
188 * Truncates a FileTime to 100-nanosecond precision.
189 *
190 * @param fileTime the FileTime to be truncated.
191 * @return the truncated FileTime.
192 * @deprecated No replacement, only used in tests.
193 */
194 @Deprecated
195 public static FileTime truncateToHundredNanos(final FileTime fileTime) {
196 final Instant instant = fileTime.toInstant();
197 return FileTime.from(Instant.ofEpochSecond(instant.getEpochSecond(), instant.getNano() / 100 * 100));
198 }
199
200 /**
201 * Converts standard Unix time (in seconds, UTC/GMT) to {@link FileTime}.
202 *
203 * @param time Unix timestamp (in seconds, UTC/GMT).
204 * @return the corresponding FileTime.
205 * @deprecated Use {@link FileTimes#fromUnixTime(long)}
206 */
207 @Deprecated
208 public static FileTime unixTimeToFileTime(final long time) {
209 return FileTimes.fromUnixTime(time);
210 }
211
212 /** Private constructor to prevent instantiation of this utility class. */
213 private TimeUtils() {
214 }
215 }