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