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}