    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 *      https://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 */
    017
    018package org.apache.commons.io.file.attribute;
    019
    020import java.io.IOException;
    021import java.math.BigDecimal;
    022import java.math.MathContext;
    023import java.math.RoundingMode;
    024import java.nio.file.Files;
    025import java.nio.file.Path;
    026import java.nio.file.attribute.FileTime;
    027import java.time.Instant;
    028import java.util.Date;
    029import java.util.concurrent.TimeUnit;
    030
    031/**
    032 * Helps use {@link FileTime} and interoperate Date and NTFS times.
    033 * <p>
    034 * An NTFS 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
    035 * Universal Time (UTC). This is the offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
    036 * </p>
    037 *
    038 * @since 2.12.0
    039 * @see <a href="https://learn.microsoft.com/en-us/windows/win32/sysinfo/file-times">NTFS File Times</a>
    040 */
    041public final class FileTimes {
    042
    043    private static final BigDecimal LONG_MIN_VALUE_BD = BigDecimal.valueOf(Long.MIN_VALUE);
    044
    045    private static final BigDecimal LONG_MAX_VALUE_BD = BigDecimal.valueOf(Long.MAX_VALUE);
    046
    047    private static final MathContext MATH_CONTEXT = new MathContext(0, RoundingMode.FLOOR);
    048
    049    /**
    050     * Constant for the {@code 1970-01-01T00:00:00Z} {@link Instant#EPOCH epoch} as a time stamp attribute.
    051     *
    052     * @see Instant#EPOCH
    053     */
    054    public static final FileTime EPOCH = FileTime.from(Instant.EPOCH);
    055
    056    /**
    057     * The offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
    058     *
    059     * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx">Windows File Times</a>
    060     * <p>
    061     * 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
    062     * Universal Time (UTC). This is the offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
    063     * </p>
    064     */
    065    static final long UNIX_TO_NTFS_OFFSET = -116444736000000000L;
    066
    067    private static final BigDecimal UNIX_TO_NTFS_OFFSET_BD = BigDecimal.valueOf(UNIX_TO_NTFS_OFFSET);
    068
    069    /**
    070     * The amount of 100-nanosecond intervals in one second.
    071     */
    072    private static final long HUNDRED_NANOS_PER_SECOND = TimeUnit.SECONDS.toNanos(1) / 100;
    073
    074    private static final BigDecimal HUNDRED_NANOS_PER_SECOND_BD = BigDecimal.valueOf(HUNDRED_NANOS_PER_SECOND);
    075
    076    /**
    077     * The amount of 100-nanosecond intervals in one millisecond.
    078     */
    079    static final long HUNDRED_NANOS_PER_MILLISECOND = TimeUnit.MILLISECONDS.toNanos(1) / 100;
    080
    081    static final BigDecimal HUNDRED_NANOS_PER_MILLISECOND_BD = BigDecimal.valueOf(HUNDRED_NANOS_PER_MILLISECOND);
    082
    083    private static final long HUNDRED = 100L;
    084
    085    private static final BigDecimal HUNDRED_BD = BigDecimal.valueOf(HUNDRED);
    086
    087    /**
    088     * Converts standard Unix time (in seconds, UTC/GMT) to {@link FileTime}.
    089     *
    090     * @param time Unix timestamp (seconds).
    091     * @return the corresponding FileTime.
    092     * @since 2.16.0
    093     */
    094    public static FileTime fromUnixTime(final long time) {
    095        return FileTime.from(time, TimeUnit.SECONDS);
    096    }
    097
    098    /**
    099     * Tests whether a FileTime can be safely represented in the standard Unix time.
    100     * <p>
    101     * If the FileTime is null, this method returns true.
    102     * </p>
    103     *
    104     * @param time the FileTime to evaluate, can be null.
    105     * @return true if the time exceeds the minimum or maximum Unix time, false otherwise.
    106     * @since 2.16.0
    107     */
    108    public static boolean isUnixTime(final FileTime time) {
    109        return isUnixTime(toUnixTime(time));
    110    }
    111
    112    /**
    113     * Tests whether a given number of seconds (since Epoch) can be safely represented in the standard Unix time.
    114     *
    115     * @param seconds the number of seconds (since Epoch) to evaluate.
    116     * @return true if the time can be represented in the standard Unix time, false otherwise.
    117     * @since 2.16.0
    118     */
    119    public static boolean isUnixTime(final long seconds) {
    120        return Integer.MIN_VALUE <= seconds && seconds <= Integer.MAX_VALUE;
    121    }
    122
    123    /**
    124     * Subtracts milliseconds from a source FileTime.
    125     *
    126     * @param fileTime         The source FileTime.
    127     * @param millisToSubtract The milliseconds to subtract.
    128     * @return The resulting FileTime.
    129     */
    130    public static FileTime minusMillis(final FileTime fileTime, final long millisToSubtract) {
    131        return FileTime.from(fileTime.toInstant().minusMillis(millisToSubtract));
    132    }
    133
    134    /**
    135     * Subtracts nanoseconds from a source FileTime.
    136     *
    137     * @param fileTime        The source FileTime.
    138     * @param nanosToSubtract The nanoseconds to subtract.
    139     * @return The resulting FileTime.
    140     */
    141    public static FileTime minusNanos(final FileTime fileTime, final long nanosToSubtract) {
    142        return FileTime.from(fileTime.toInstant().minusNanos(nanosToSubtract));
    143    }
    144
    145    /**
    146     * Subtracts seconds from a source FileTime.
    147     *
    148     * @param fileTime          The source FileTime.
    149     * @param secondsToSubtract The seconds to subtract.
    150     * @return The resulting FileTime.
    151     */
    152    public static FileTime minusSeconds(final FileTime fileTime, final long secondsToSubtract) {
    153        return FileTime.from(fileTime.toInstant().minusSeconds(secondsToSubtract));
    154    }
    155
    156    /**
    157     * Obtains the current instant FileTime from the system clock.
    158     *
    159     * @return the current instant FileTime from the system clock.
    160     */
    161    public static FileTime now() {
    162        return FileTime.from(Instant.now());
    163    }
    164
    165    static Date ntfsTimeToDate(final BigDecimal ntfsTime) {
    166        return new Date(ntfsTimeToInstant(ntfsTime).toEpochMilli());
    167    }
    168
    169    /**
    170     * Converts an NTFS time (100 nanosecond units since 1 January 1601) to a {@link Date}.
    171     * <p>
    172     * An NTFS file time is a 64-bit value for the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
    173     * </p>
    174     *
    175     * @param ntfsTime the NTFS time, 100-nanosecond units since 1 January 1601.
    176     * @return the Date input.
    177     * @see <a href="https://learn.microsoft.com/en-us/windows/win32/sysinfo/file-times">NTFS File Times</a>
    178     */
    179    public static Date ntfsTimeToDate(final long ntfsTime) {
    180        return ntfsTimeToDate(BigDecimal.valueOf(ntfsTime));
    181    }
    182
    183    /**
    184     * Converts an NTFS time (100-nanosecond units since 1 January 1601) to a {@link FileTime}.
    185     * <p>
    186     * An NTFS file time is a 64-bit value for the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
    187     * </p>
    188     *
    189     * @param ntfsTime the NTFS time, 100-nanosecond units since 1 January 1601.
    190     * @return the FileTime input.
    191     * @see #toNtfsTime(FileTime)
    192     * @see <a href="https://learn.microsoft.com/en-us/windows/win32/sysinfo/file-times">NTFS File Times</a>
    193     */
    194    public static FileTime ntfsTimeToFileTime(final long ntfsTime) {
    195        return FileTime.from(ntfsTimeToInstant(ntfsTime));
    196    }
    197
    198    static Instant ntfsTimeToInstant(final BigDecimal ntfsTime) {
    199        final BigDecimal javaHundredsNanos = ntfsTime.add(UNIX_TO_NTFS_OFFSET_BD);
    200        final BigDecimal[] dar = javaHundredsNanos.divideAndRemainder(HUNDRED_NANOS_PER_SECOND_BD, MATH_CONTEXT);
    201        return Instant.ofEpochSecond(dar[0].longValueExact(), dar[1].multiply(HUNDRED_BD).longValueExact());
    202    }
    203
    204    static Instant ntfsTimeToInstant(final long ntfsTime) {
    205        return ntfsTimeToInstant(BigDecimal.valueOf(ntfsTime));
    206    }
    207
    208    /**
    209     * Adds milliseconds to a {@link FileTime}.
    210     *
    211     * @param fileTime    The source FileTime.
    212     * @param millisToAdd The milliseconds to add.
    213     * @return The resulting FileTime.
    214     */
    215    public static FileTime plusMillis(final FileTime fileTime, final long millisToAdd) {
    216        return FileTime.from(fileTime.toInstant().plusMillis(millisToAdd));
    217    }
    218
    219    /**
    220     * Adds nanoseconds to a {@link FileTime}.
    221     *
    222     * @param fileTime        The source FileTime.
    223     * @param nanosToSubtract The nanoseconds to subtract.
    224     * @return The resulting FileTime.
    225     */
    226    public static FileTime plusNanos(final FileTime fileTime, final long nanosToSubtract) {
    227        return FileTime.from(fileTime.toInstant().plusNanos(nanosToSubtract));
    228    }
    229
    230    /**
    231     * Adds seconds to a {@link FileTime}.
    232     *
    233     * @param fileTime     The source FileTime.
    234     * @param secondsToAdd The seconds to add.
    235     * @return The resulting FileTime.
    236     */
    237    public static FileTime plusSeconds(final FileTime fileTime, final long secondsToAdd) {
    238        return FileTime.from(fileTime.toInstant().plusSeconds(secondsToAdd));
    239    }
    240
    241    /**
    242     * Sets the last modified time of the given file path to now.
    243     *
    244     * @param path The file path to set.
    245     * @throws IOException if an I/O error occurs.
    246     */
    247    public static void setLastModifiedTime(final Path path) throws IOException {
    248        Files.setLastModifiedTime(path, now());
    249    }
    250
    251    /**
    252     * Converts a {@link FileTime} to a {@link Date}. If the provided FileTime is {@code null}, the returned Date is also {@code null}.
    253     *
    254     * @param fileTime the file time to be converted.
    255     * @return a {@link Date} which corresponds to the supplied time, or {@code null} if the time is {@code null}.
    256     * @see #toFileTime(Date)
    257     */
    258    public static Date toDate(final FileTime fileTime) {
    259        return fileTime != null ? new Date(fileTime.toMillis()) : null;
    260    }
    261
    262    /**
    263     * Converts a {@link Date} to a {@link FileTime}. If the provided Date is {@code null}, the returned FileTime is also {@code null}.
    264     *
    265     * @param date the date to be converted.
    266     * @return a {@link FileTime} which corresponds to the supplied date, or {@code null} if the date is {@code null}.
    267     * @see #toDate(FileTime)
    268     */
    269    public static FileTime toFileTime(final Date date) {
    270        return date != null ? FileTime.fromMillis(date.getTime()) : null;
    271    }
    272
    273    /**
    274     * Converts a {@link Date} to NTFS time.
    275     * <p>
    276     * An NTFS file time is a 64-bit value for the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
    277     * </p>
    278     *
    279     * @param date the Date input.
    280     * @return the NTFS time, 100-nanosecond units since 1 January 1601.
    281     */
    282    public static long toNtfsTime(final Date date) {
    283        return toNtfsTime(date.getTime());
    284    }
    285
    286    /**
    287     * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601).
    288     * <p>
    289     * An NTFS file time is a 64-bit value for the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
    290     * </p>
    291     *
    292     * @param fileTime the FileTime input.
    293     * @return the NTFS time, 100-nanosecond units since 1 January 1601.
    294     */
    295    public static long toNtfsTime(final FileTime fileTime) {
    296        return toNtfsTime(fileTime.toInstant());
    297    }
    298
    299    static long toNtfsTime(final Instant instant) {
    300        final BigDecimal javaHundredNanos = BigDecimal.valueOf(instant.getEpochSecond()).multiply(HUNDRED_NANOS_PER_SECOND_BD)
    301                .add(BigDecimal.valueOf(instant.getNano() / 100));
    302        return javaHundredNanos.subtract(UNIX_TO_NTFS_OFFSET_BD).longValueExact();
    303    }
    304
    305    /**
    306     * Converts a Java time (milliseconds since Epoch) to NTFS time.
    307     * <p>
    308     * An NTFS file time is a 64-bit value for the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
    309     * </p>
    310     *
    311     * @param javaTime the Java time
    312     * @return the NTFS time, 100-nanosecond units since 1 January 1601.
    313     * @since 2.16.0
    314     */
    315    public static long toNtfsTime(final long javaTime) {
    316        final BigDecimal javaHundredNanos = BigDecimal.valueOf(javaTime).multiply(HUNDRED_NANOS_PER_MILLISECOND_BD);
    317        final BigDecimal ntfsTime = javaHundredNanos.subtract(UNIX_TO_NTFS_OFFSET_BD);
    318        if (ntfsTime.compareTo(LONG_MAX_VALUE_BD) >= 0) {
    319            return Long.MAX_VALUE;
    320        }
    321        if (ntfsTime.compareTo(LONG_MIN_VALUE_BD) <= 0) {
    322            return Long.MIN_VALUE;
    323        }
    324        return ntfsTime.longValue();
    325    }
    326
    327    /**
    328     * Converts a {@link FileTime} to standard Unix time in seconds.
    329     * <p>
    330     * The returned seconds value may lie out of bounds of Unix time. Check with {@link FileTimes#isUnixTime(long)}.
    331     * </p>
    332     *
    333     * @param fileTime the original FileTime.
    334     * @return the Unix timestamp or 0 if the input is null.
    335     * @see #isUnixTime(long)
    336     * @since 2.16.0
    337     */
    338    public static long toUnixTime(final FileTime fileTime) {
    339        return fileTime != null ? fileTime.to(TimeUnit.SECONDS) : 0;
    340    }
    341
    342    private FileTimes() {
    343        // No instances.
    344    }
    345}