001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one or more
003 *  contributor license agreements.  See the NOTICE file distributed with
004 *  this work for additional information regarding copyright ownership.
005 *  The ASF licenses this file to You under the Apache License, Version 2.0
006 *  (the "License"); you may not use this file except in compliance with
007 *  the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS,
013 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 *  See the License for the specific language governing permissions and
015 *  limitations under the License.
016 */
017package org.apache.commons.compress.utils;
018
019import java.nio.file.attribute.FileTime;
020import java.time.Instant;
021import java.util.Date;
022import java.util.concurrent.TimeUnit;
023
024import org.apache.commons.io.file.attribute.FileTimes;
025
026/**
027 * Utility class for handling time-related types and conversions.
028 * <p>
029 * Understanding UNIX vs NTFS timestamps:
030 * </p>
031 * <ul>
032 * <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
033 * Universal Time (UTC)</li>
034 * <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
035 * number of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).</li>
036 * </ul>
037 *
038 * @since 1.23
039 */
040public final class TimeUtils {
041
042    /** The amount of 100-nanosecond intervals in one millisecond. */
043    static final long HUNDRED_NANOS_PER_MILLISECOND = TimeUnit.MILLISECONDS.toNanos(1) / 100;
044
045    /**
046     * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx">Windows File Times</a>
047     * <p>
048     * 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
049     * Universal Time (UTC). This is the offset of Windows time 0 to UNIX epoch in 100-nanosecond intervals.
050     * </p>
051     */
052    static final long WINDOWS_EPOCH_OFFSET = -116444736000000000L;
053
054    /**
055     * Tests whether a FileTime can be safely represented in the standard UNIX time.
056     *
057     * <p>
058     * TODO ? If the FileTime is null, this method always returns true.
059     * </p>
060     *
061     * @param time the FileTime to evaluate, can be null.
062     * @return true if the time exceeds the minimum or maximum UNIX time, false otherwise.
063     * @deprecated use {@link FileTimes#isUnixTime(FileTime)}
064     */
065    @Deprecated
066    public static boolean isUnixTime(final FileTime time) {
067        return FileTimes.isUnixTime(time);
068    }
069
070    /**
071     * Tests whether a given number of seconds (since Epoch) can be safely represented in the standard UNIX time.
072     *
073     * @param seconds the number of seconds (since Epoch) to evaluate.
074     * @return true if the time can be represented in the standard UNIX time, false otherwise.
075     * @deprecated Use {@link FileTimes#isUnixTime(long)}
076     */
077    @Deprecated
078    public static boolean isUnixTime(final long seconds) {
079        return FileTimes.isUnixTime(seconds);
080    }
081
082    /**
083     * Converts NTFS time (100 nanosecond units since 1 January 1601) to Java time.
084     *
085     * @param ntfsTime the NTFS time in 100 nanosecond units.
086     * @return the Date.
087     * @deprecated Use {@link FileTimes#ntfsTimeToDate(long)}.
088     */
089    @Deprecated
090    public static Date ntfsTimeToDate(final long ntfsTime) {
091        return FileTimes.ntfsTimeToDate(ntfsTime);
092    }
093
094    /**
095     * Converts NTFS time (100-nanosecond units since 1 January 1601) to a FileTime.
096     *
097     * @param ntfsTime the NTFS time in 100-nanosecond units.
098     * @return the FileTime.
099     * @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}