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 */ 064 public static boolean isUnixTime(final FileTime time) { 065 // TODO Apache Commons IO 2.16.0 066 return 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 // TODO Apache Commons IO 2.16.0 077 return Integer.MIN_VALUE <= seconds && seconds <= Integer.MAX_VALUE; 078 } 079 080 /** 081 * Converts NTFS time (100 nanosecond units since 1 January 1601) to Java time. 082 * 083 * @param ntfsTime the NTFS time in 100 nanosecond units. 084 * @return the Date. 085 * @deprecated Use {@link FileTimes#ntfsTimeToDate(long)}. 086 */ 087 @Deprecated 088 public static Date ntfsTimeToDate(final long ntfsTime) { 089 return FileTimes.ntfsTimeToDate(ntfsTime); 090 } 091 092 /** 093 * Converts NTFS time (100-nanosecond units since 1 January 1601) to a FileTime. 094 * 095 * @param ntfsTime the NTFS time in 100-nanosecond units. 096 * @return the FileTime. 097 * @see FileTimes#toNtfsTime(FileTime) 098 * @deprecated Use {@link FileTimes#ntfsTimeToFileTime(long)}. 099 */ 100 @Deprecated 101 public static FileTime ntfsTimeToFileTime(final long ntfsTime) { 102 return FileTimes.ntfsTimeToFileTime(ntfsTime); 103 } 104 105 /** 106 * Converts {@link FileTime} to a {@link Date}. If the provided FileTime is {@code null}, the returned Date is also {@code null}. 107 * 108 * @param fileTime the file time to be converted. 109 * @return a {@link Date} which corresponds to the supplied time, or {@code null} if the time is {@code null}. 110 * @see FileTimes#toFileTime(Date) 111 * @deprecated Use {@link FileTimes#toDate(FileTime)}. 112 */ 113 @Deprecated 114 public static Date toDate(final FileTime fileTime) { 115 return FileTimes.toDate(fileTime); 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 FileTimes#toDate(FileTime) 124 * @deprecated Use {@link FileTimes#toFileTime(Date)}. 125 */ 126 @Deprecated 127 public static FileTime toFileTime(final Date date) { 128 return FileTimes.toFileTime(date); 129 } 130 131 /** 132 * Converts a {@link Date} to NTFS time. 133 * 134 * @param date the Date. 135 * @return the NTFS time. 136 * @deprecated Use {@link FileTimes#toNtfsTime(Date)}. 137 */ 138 @Deprecated 139 public static long toNtfsTime(final Date date) { 140 return FileTimes.toNtfsTime(date); 141 } 142 143 /** 144 * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601). 145 * 146 * @param fileTime the FileTime. 147 * @return the NTFS time in 100-nanosecond units. 148 * @see FileTimes#ntfsTimeToFileTime(long) 149 * @deprecated Use {@link FileTimes#toNtfsTime(FileTime)}. 150 */ 151 @Deprecated 152 public static long toNtfsTime(final FileTime fileTime) { 153 return FileTimes.toNtfsTime(fileTime); 154 } 155 156 /** 157 * Converts Java time (milliseconds since Epoch) to NTFS time. 158 * 159 * @param javaTime the Java time. 160 * @return the NTFS time. 161 */ 162 public static long toNtfsTime(final long javaTime) { 163 // TODO Apache Commons IO 2.16.0 164 final long javaHundredNanos = javaTime * HUNDRED_NANOS_PER_MILLISECOND; 165 return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET); 166 } 167 168 /** 169 * Converts {@link FileTime} to standard UNIX time. 170 * 171 * @param fileTime the original FileTime. 172 * @return the UNIX timestamp. 173 */ 174 public static long toUnixTime(final FileTime fileTime) { 175 // TODO Apache Commons IO 2.16.0 176 return fileTime != null ? fileTime.to(TimeUnit.SECONDS) : 0; 177 } 178 179 /** 180 * Truncates a FileTime to 100-nanosecond precision. 181 * 182 * @param fileTime the FileTime to be truncated. 183 * @return the truncated FileTime. 184 */ 185 public static FileTime truncateToHundredNanos(final FileTime fileTime) { 186 final Instant instant = fileTime.toInstant(); 187 return FileTime.from(Instant.ofEpochSecond(instant.getEpochSecond(), instant.getNano() / 100 * 100)); 188 } 189 190 /** 191 * Converts standard UNIX time (in seconds, UTC/GMT) to {@link FileTime}. 192 * 193 * @param time UNIX timestamp (in seconds, UTC/GMT). 194 * @return the corresponding FileTime. 195 */ 196 public static FileTime unixTimeToFileTime(final long time) { 197 // TODO Apache Commons IO 2.16.0 FileTimes.fromUnixTime(long) 198 return FileTime.from(time, TimeUnit.SECONDS); 199 } 200 201 /** Private constructor to prevent instantiation of this utility class. */ 202 private TimeUtils() { 203 } 204}