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
024/**
025 * Utility class for handling time-related types and conversions.
026 * <p>
027 * Understanding Unix vs NTFS timestamps:
028 * </p>
029 * <ul>
030 * <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
031 * Universal Time (UTC)</li>
032 * <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 number
033 * of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).</li>
034 * </ul>
035 *
036 * @since 1.23
037 */
038public final class TimeUtils {
039
040    /** The amount of 100-nanosecond intervals in one millisecond. */
041    static final long HUNDRED_NANOS_PER_MILLISECOND = TimeUnit.MILLISECONDS.toNanos(1) / 100;
042
043    /** The amount of 100-nanosecond intervals in one second. */
044    static final long HUNDRED_NANOS_PER_SECOND = TimeUnit.SECONDS.toNanos(1) / 100;
045
046    /**
047     * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx">Windows File Times</a>
048     * <p>
049     * 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
050     * Universal Time (UTC). This is the offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
051     * </p>
052     */
053    static final long WINDOWS_EPOCH_OFFSET = -116444736000000000L;
054
055    /**
056     * Tests whether a FileTime can be safely represented in the standard UNIX time.
057     *
058     * <p>
059     * TODO ? If the FileTime is null, this method always returns true.
060     * </p>
061     *
062     * @param time the FileTime to evaluate, can be null
063     * @return true if the time exceeds the minimum or maximum UNIX time, false otherwise
064     */
065    public static boolean isUnixTime(final FileTime time) {
066        return time == null ? true : isUnixTime(toUnixTime(time));
067    }
068
069    /**
070     * Tests whether a given number of seconds (since Epoch) can be safely represented in the standard UNIX time.
071     *
072     * @param seconds the number of seconds (since Epoch) to evaluate
073     * @return true if the time can be represented in the standard UNIX time, false otherwise
074     */
075    public static boolean isUnixTime(final long seconds) {
076        return Integer.MIN_VALUE <= seconds && seconds <= Integer.MAX_VALUE;
077    }
078
079    /**
080     * Converts NTFS time (100 nanosecond units since 1 January 1601) to Java time.
081     *
082     * @param ntfsTime the NTFS time in 100 nanosecond units
083     * @return the Date
084     */
085    public static Date ntfsTimeToDate(final long ntfsTime) {
086        final long javaHundredNanos = Math.addExact(ntfsTime, WINDOWS_EPOCH_OFFSET);
087        final long javaMillis = Math.floorDiv(javaHundredNanos, HUNDRED_NANOS_PER_MILLISECOND);
088        return new Date(javaMillis);
089    }
090
091    /**
092     * Converts NTFS time (100-nanosecond units since 1 January 1601) to a FileTime.
093     *
094     * @param ntfsTime the NTFS time in 100-nanosecond units
095     * @return the FileTime
096     *
097     * @see TimeUtils#WINDOWS_EPOCH_OFFSET
098     * @see TimeUtils#toNtfsTime(FileTime)
099     */
100    public static FileTime ntfsTimeToFileTime(final long ntfsTime) {
101        final long javaHundredsNanos = Math.addExact(ntfsTime, WINDOWS_EPOCH_OFFSET);
102        final long javaSeconds = Math.floorDiv(javaHundredsNanos, HUNDRED_NANOS_PER_SECOND);
103        final long javaNanos = Math.floorMod(javaHundredsNanos, HUNDRED_NANOS_PER_SECOND) * 100;
104        return FileTime.from(Instant.ofEpochSecond(javaSeconds, javaNanos));
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 TimeUtils#toFileTime(Date)
113     */
114    public static Date toDate(final FileTime fileTime) {
115        return fileTime != null ? new Date(fileTime.toMillis()) : null;
116    }
117
118    /**
119     * Converts {@link Date} to a {@link FileTime}. If the provided Date is {@code null}, the returned FileTime is also {@code null}.
120     *
121     * @param date the date to be converted.
122     * @return a {@link FileTime} which corresponds to the supplied date, or {@code null} if the date is {@code null}.
123     * @see TimeUtils#toDate(FileTime)
124     */
125    public static FileTime toFileTime(final Date date) {
126        return date != null ? FileTime.fromMillis(date.getTime()) : null;
127    }
128
129    /**
130     * Converts a {@link Date} to NTFS time.
131     *
132     * @param date the Date
133     * @return the NTFS time
134     */
135    public static long toNtfsTime(final Date date) {
136        return toNtfsTime(date.getTime());
137    }
138
139    /**
140     * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601).
141     *
142     * @param fileTime the FileTime
143     * @return the NTFS time in 100-nanosecond units
144     *
145     * @see TimeUtils#WINDOWS_EPOCH_OFFSET
146     * @see TimeUtils#ntfsTimeToFileTime(long)
147     */
148    public static long toNtfsTime(final FileTime fileTime) {
149        final Instant instant = fileTime.toInstant();
150        final long javaHundredNanos = (instant.getEpochSecond() * HUNDRED_NANOS_PER_SECOND) + (instant.getNano() / 100);
151        return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET);
152    }
153
154    /**
155     * Converts Java time (milliseconds since Epoch) to NTFS time.
156     *
157     * @param javaTime the Java time
158     * @return the NTFS time
159     */
160    public static long toNtfsTime(final long javaTime) {
161        final long javaHundredNanos = javaTime * HUNDRED_NANOS_PER_MILLISECOND;
162        return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET);
163    }
164
165    /**
166     * Converts {@link FileTime} to standard UNIX time.
167     *
168     * @param fileTime the original FileTime
169     * @return the UNIX timestamp
170     */
171    public static long toUnixTime(final FileTime fileTime) {
172        return fileTime.to(TimeUnit.SECONDS);
173    }
174
175    /**
176     * Truncates a FileTime to 100-nanosecond precision.
177     *
178     * @param fileTime the FileTime to be truncated
179     * @return the truncated FileTime
180     */
181    public static FileTime truncateToHundredNanos(final FileTime fileTime) {
182        final Instant instant = fileTime.toInstant();
183        return FileTime.from(Instant.ofEpochSecond(instant.getEpochSecond(), (instant.getNano() / 100) * 100));
184    }
185
186    /**
187     * Converts standard UNIX time (in seconds, UTC/GMT) to {@link FileTime}.
188     *
189     * @param time UNIX timestamp
190     * @return the corresponding FileTime
191     */
192    public static FileTime unixTimeToFileTime(final long time) {
193        return FileTime.from(time, TimeUnit.SECONDS);
194    }
195
196    /** Private constructor to prevent instantiation of this utility class. */
197    private TimeUtils() {
198    }
199}