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 }