View Javadoc
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    *      http://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  package org.apache.commons.compress.utils;
18  
19  import java.nio.file.attribute.FileTime;
20  import java.time.Instant;
21  import java.util.Date;
22  import java.util.concurrent.TimeUnit;
23  
24  import org.apache.commons.io.file.attribute.FileTimes;
25  
26  /**
27   * Utility class for handling time-related types and conversions.
28   * <p>
29   * Understanding UNIX vs NTFS timestamps:
30   * </p>
31   * <ul>
32   * <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
33   * Universal Time (UTC)</li>
34   * <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
35   * number of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).</li>
36   * </ul>
37   *
38   * @since 1.23
39   */
40  public final class TimeUtils {
41  
42      /** The amount of 100-nanosecond intervals in one millisecond. */
43      static final long HUNDRED_NANOS_PER_MILLISECOND = TimeUnit.MILLISECONDS.toNanos(1) / 100;
44  
45      /**
46       * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx">Windows File Times</a>
47       * <p>
48       * 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
49       * Universal Time (UTC). This is the offset of Windows time 0 to UNIX epoch in 100-nanosecond intervals.
50       * </p>
51       */
52      static final long WINDOWS_EPOCH_OFFSET = -116444736000000000L;
53  
54      /**
55       * Tests whether a FileTime can be safely represented in the standard UNIX time.
56       *
57       * <p>
58       * TODO ? If the FileTime is null, this method always returns true.
59       * </p>
60       *
61       * @param time the FileTime to evaluate, can be null.
62       * @return true if the time exceeds the minimum or maximum UNIX time, false otherwise.
63       * @deprecated use {@link FileTimes#isUnixTime(FileTime)}
64       */
65      @Deprecated
66      public static boolean isUnixTime(final FileTime time) {
67          return FileTimes.isUnixTime(time);
68      }
69  
70      /**
71       * Tests whether a given number of seconds (since Epoch) can be safely represented in the standard UNIX time.
72       *
73       * @param seconds the number of seconds (since Epoch) to evaluate.
74       * @return true if the time can be represented in the standard UNIX time, false otherwise.
75       * @deprecated Use {@link FileTimes#isUnixTime(long)}
76       */
77      @Deprecated
78      public static boolean isUnixTime(final long seconds) {
79          return FileTimes.isUnixTime(seconds);
80      }
81  
82      /**
83       * Converts NTFS time (100 nanosecond units since 1 January 1601) to Java time.
84       *
85       * @param ntfsTime the NTFS time in 100 nanosecond units.
86       * @return the Date.
87       * @deprecated Use {@link FileTimes#ntfsTimeToDate(long)}.
88       */
89      @Deprecated
90      public static Date ntfsTimeToDate(final long ntfsTime) {
91          return FileTimes.ntfsTimeToDate(ntfsTime);
92      }
93  
94      /**
95       * Converts NTFS time (100-nanosecond units since 1 January 1601) to a FileTime.
96       *
97       * @param ntfsTime the NTFS time in 100-nanosecond units.
98       * @return the FileTime.
99       * @see FileTimes#toNtfsTime(FileTime)
100      * @deprecated Use {@link FileTimes#ntfsTimeToFileTime(long)}.
101      */
102     @Deprecated
103     public static FileTime ntfsTimeToFileTime(final long ntfsTime) {
104         return FileTimes.ntfsTimeToFileTime(ntfsTime);
105     }
106 
107     /**
108      * Converts {@link FileTime} to a {@link Date}. If the provided FileTime is {@code null}, the returned Date is also {@code null}.
109      *
110      * @param fileTime the file time to be converted.
111      * @return a {@link Date} which corresponds to the supplied time, or {@code null} if the time is {@code null}.
112      * @see FileTimes#toFileTime(Date)
113      * @deprecated Use {@link FileTimes#toDate(FileTime)}.
114      */
115     @Deprecated
116     public static Date toDate(final FileTime fileTime) {
117         return FileTimes.toDate(fileTime);
118     }
119 
120     /**
121      * Converts {@link Date} to a {@link FileTime}. If the provided Date is {@code null}, the returned FileTime is also {@code null}.
122      *
123      * @param date the date to be converted.
124      * @return a {@link FileTime} which corresponds to the supplied date, or {@code null} if the date is {@code null}.
125      * @see FileTimes#toDate(FileTime)
126      * @deprecated Use {@link FileTimes#toFileTime(Date)}.
127      */
128     @Deprecated
129     public static FileTime toFileTime(final Date date) {
130         return FileTimes.toFileTime(date);
131     }
132 
133     /**
134      * Converts a {@link Date} to NTFS time.
135      *
136      * @param date the Date.
137      * @return the NTFS time.
138      * @deprecated Use {@link FileTimes#toNtfsTime(Date)}.
139      */
140     @Deprecated
141     public static long toNtfsTime(final Date date) {
142         return FileTimes.toNtfsTime(date);
143     }
144 
145     /**
146      * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601).
147      *
148      * @param fileTime the FileTime.
149      * @return the NTFS time in 100-nanosecond units.
150      * @see FileTimes#ntfsTimeToFileTime(long)
151      * @deprecated Use {@link FileTimes#toNtfsTime(FileTime)}.
152      */
153     @Deprecated
154     public static long toNtfsTime(final FileTime fileTime) {
155         return FileTimes.toNtfsTime(fileTime);
156     }
157 
158     /**
159      * Converts Java time (milliseconds since Epoch) to NTFS time.
160      *
161      * @param javaTime the Java time.
162      * @return the NTFS time.
163      * @deprecated Use {@link FileTimes#toNtfsTime(long)}
164      */
165     @Deprecated
166     public static long toNtfsTime(final long javaTime) {
167         return FileTimes.toNtfsTime(javaTime);
168     }
169 
170     /**
171      * Converts {@link FileTime} to standard UNIX time.
172      *
173      * @param fileTime the original FileTime.
174      * @return the UNIX timestamp.
175      */
176     public static long toUnixTime(final FileTime fileTime) {
177         return FileTimes.toUnixTime(fileTime);
178     }
179 
180     /**
181      * Truncates a FileTime to 100-nanosecond precision.
182      *
183      * @param fileTime the FileTime to be truncated.
184      * @return the truncated FileTime.
185      */
186     public static FileTime truncateToHundredNanos(final FileTime fileTime) {
187         final Instant instant = fileTime.toInstant();
188         return FileTime.from(Instant.ofEpochSecond(instant.getEpochSecond(), instant.getNano() / 100 * 100));
189     }
190 
191     /**
192      * Converts standard UNIX time (in seconds, UTC/GMT) to {@link FileTime}.
193      *
194      * @param time UNIX timestamp (in seconds, UTC/GMT).
195      * @return the corresponding FileTime.
196      * @deprecated Use {@link FileTimes#fromUnixTime(long)}
197      */
198     @Deprecated
199     public static FileTime unixTimeToFileTime(final long time) {
200         return FileTimes.fromUnixTime(time);
201     }
202 
203     /** Private constructor to prevent instantiation of this utility class. */
204     private TimeUtils() {
205     }
206 }