You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/01/01 13:28:32 UTC
[commons-compress] 04/04: Javdoc
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git
commit 39da8401b4c47fe99f6ebeed3503a89bea5f614d
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Jan 1 08:28:23 2023 -0500
Javdoc
- sort members
- Use ternary expression
- Remove unused API
- better parameter name
---
.../apache/commons/compress/utils/TimeUtils.java | 115 ++++++++++-----------
.../archivers/zip/ZipArchiveEntryTest.java | 3 -
2 files changed, 54 insertions(+), 64 deletions(-)
diff --git a/src/main/java/org/apache/commons/compress/utils/TimeUtils.java b/src/main/java/org/apache/commons/compress/utils/TimeUtils.java
index b6db4d64..c8349f91 100644
--- a/src/main/java/org/apache/commons/compress/utils/TimeUtils.java
+++ b/src/main/java/org/apache/commons/compress/utils/TimeUtils.java
@@ -24,6 +24,15 @@ import java.util.concurrent.TimeUnit;
/**
* Utility class for handling time-related types and conversions.
+ * <p>
+ * Understanding Unix vs NTFS timestamps:
+ * </p>
+ * <ul>
+ * <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
+ * Universal Time (UTC)</li>
+ * <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
+ * of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).</li>
+ * </ul>
*
* @since 1.23
*/
@@ -38,58 +47,24 @@ public final class TimeUtils {
/**
* <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724290%28v=vs.85%29.aspx">Windows File Times</a>
* <p>
- * 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 Universal Time (UTC).
- * This is the offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
+ * 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
+ * Universal Time (UTC). This is the offset of Windows time 0 to Unix epoch in 100-nanosecond intervals.
* </p>
*/
static final long WINDOWS_EPOCH_OFFSET = -116444736000000000L;
- /**
- * Converts standard UNIX time (in seconds, UTC/GMT) to {@link FileTime}.
- *
- * @param time UNIX timestamp
- * @return the corresponding FileTime
- */
- public static FileTime unixTimeToFileTime(final long time) {
- return FileTime.from(time, TimeUnit.SECONDS);
- }
-
- /**
- * Converts {@link FileTime} to standard UNIX time.
- *
- * @param time the original FileTime
- * @return the UNIX timestamp
- */
- public static long toUnixTime(final FileTime time) {
- return time.to(TimeUnit.SECONDS);
- }
-
- /**
- * Converts Java time (milliseconds since Epoch) to standard UNIX time.
- *
- * @param time the original Java time
- * @return the UNIX timestamp
- */
- public static long javaTimeToUnixTime(final long time) {
- return time / 1000L;
- }
-
/**
* Tests whether a FileTime can be safely represented in the standard UNIX time.
*
- * <p>If the FileTime is null, this method always returns true.</p>
+ * <p>
+ * TODO ? If the FileTime is null, this method always returns true.
+ * </p>
*
* @param time the FileTime to evaluate, can be null
* @return true if the time exceeds the minimum or maximum UNIX time, false otherwise
*/
public static boolean isUnixTime(final FileTime time) {
- if (time == null) {
- return true;
- }
- final long fileTimeToUnixTime = toUnixTime(time);
- return isUnixTime(fileTimeToUnixTime);
+ return time == null ? true : isUnixTime(toUnixTime(time));
}
/**
@@ -131,20 +106,18 @@ public final class TimeUtils {
}
/**
- * Converts {@link FileTime} to a {@link Date}.
- * If the provided FileTime is {@code null}, the returned Date is also {@code null}.
+ * Converts {@link FileTime} to a {@link Date}. If the provided FileTime is {@code null}, the returned Date is also {@code null}.
*
- * @param time the file time to be converted.
+ * @param fileTime the file time to be converted.
* @return a {@link Date} which corresponds to the supplied time, or {@code null} if the time is {@code null}.
* @see TimeUtils#toFileTime(Date)
*/
- public static Date toDate(final FileTime time) {
- return time != null ? new Date(time.toMillis()) : null;
+ public static Date toDate(final FileTime fileTime) {
+ return fileTime != null ? new Date(fileTime.toMillis()) : null;
}
/**
- * Converts {@link Date} to a {@link FileTime}.
- * If the provided Date is {@code null}, the returned FileTime is also {@code null}.
+ * Converts {@link Date} to a {@link FileTime}. If the provided Date is {@code null}, the returned FileTime is also {@code null}.
*
* @param date the date to be converted.
* @return a {@link FileTime} which corresponds to the supplied date, or {@code null} if the date is {@code null}.
@@ -164,30 +137,40 @@ public final class TimeUtils {
return toNtfsTime(date.getTime());
}
+ /**
+ * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601).
+ *
+ * @param fileTime the FileTime
+ * @return the NTFS time in 100-nanosecond units
+ *
+ * @see TimeUtils#WINDOWS_EPOCH_OFFSET
+ * @see TimeUtils#ntfsTimeToFileTime(long)
+ */
+ public static long toNtfsTime(final FileTime fileTime) {
+ final Instant instant = fileTime.toInstant();
+ final long javaHundredNanos = (instant.getEpochSecond() * HUNDRED_NANOS_PER_SECOND) + (instant.getNano() / 100);
+ return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET);
+ }
+
/**
* Converts Java time (milliseconds since Epoch) to NTFS time.
*
- * @param time the Java time
+ * @param javaTime the Java time
* @return the NTFS time
*/
- public static long toNtfsTime(final long time) {
- final long javaHundredNanos = time * HUNDRED_NANOS_PER_MILLISECOND;
+ public static long toNtfsTime(final long javaTime) {
+ final long javaHundredNanos = javaTime * HUNDRED_NANOS_PER_MILLISECOND;
return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET);
}
/**
- * Converts a {@link FileTime} to NTFS time (100-nanosecond units since 1 January 1601).
- *
- * @param time the FileTime
- * @return the NTFS time in 100-nanosecond units
+ * Converts {@link FileTime} to standard UNIX time.
*
- * @see TimeUtils#WINDOWS_EPOCH_OFFSET
- * @see TimeUtils#ntfsTimeToFileTime(long)
+ * @param fileTime the original FileTime
+ * @return the UNIX timestamp
*/
- public static long toNtfsTime(final FileTime time) {
- final Instant instant = time.toInstant();
- final long javaHundredNanos = (instant.getEpochSecond() * HUNDRED_NANOS_PER_SECOND) + (instant.getNano() / 100);
- return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET);
+ public static long toUnixTime(final FileTime fileTime) {
+ return fileTime.to(TimeUnit.SECONDS);
}
/**
@@ -201,7 +184,17 @@ public final class TimeUtils {
return FileTime.from(Instant.ofEpochSecond(instant.getEpochSecond(), (instant.getNano() / 100) * 100));
}
+ /**
+ * Converts standard UNIX time (in seconds, UTC/GMT) to {@link FileTime}.
+ *
+ * @param time UNIX timestamp
+ * @return the corresponding FileTime
+ */
+ public static FileTime unixTimeToFileTime(final long time) {
+ return FileTime.from(time, TimeUnit.SECONDS);
+ }
+
/** Private constructor to prevent instantiation of this utility class. */
- private TimeUtils(){
+ private TimeUtils() {
}
}
diff --git a/src/test/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryTest.java b/src/test/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryTest.java
index aad70c47..fccbc076 100644
--- a/src/test/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryTest.java
+++ b/src/test/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryTest.java
@@ -465,7 +465,6 @@ public class ZipArchiveEntryTest {
assertEquals(time, ze.getLastModifiedTime().toMillis());
X5455_ExtendedTimestamp extendedTimestamp = (X5455_ExtendedTimestamp) ze.getExtraField(X5455_ExtendedTimestamp.HEADER_ID);
assertNotNull(extendedTimestamp);
- assertEquals(TimeUtils.javaTimeToUnixTime(time), extendedTimestamp.getModifyTime().getValue());
assertEquals(TimeUtils.toUnixTime(lastAccessTime), extendedTimestamp.getAccessTime().getValue());
assertNull(extendedTimestamp.getCreateTime());
X000A_NTFS ntfs = (X000A_NTFS) ze.getExtraField(X000A_NTFS.HEADER_ID);
@@ -487,7 +486,6 @@ public class ZipArchiveEntryTest {
assertEquals(time, ze.getLastModifiedTime().toMillis());
X5455_ExtendedTimestamp extendedTimestamp = (X5455_ExtendedTimestamp) ze.getExtraField(X5455_ExtendedTimestamp.HEADER_ID);
assertNotNull(extendedTimestamp);
- assertEquals(TimeUtils.javaTimeToUnixTime(time), extendedTimestamp.getModifyTime().getValue());
assertNull(extendedTimestamp.getAccessTime());
assertEquals(TimeUtils.toUnixTime(creationTime), extendedTimestamp.getCreateTime().getValue());
X000A_NTFS ntfs = (X000A_NTFS) ze.getExtraField(X000A_NTFS.HEADER_ID);
@@ -511,7 +509,6 @@ public class ZipArchiveEntryTest {
assertEquals(time, ze.getLastModifiedTime().toMillis());
X5455_ExtendedTimestamp extendedTimestamp = (X5455_ExtendedTimestamp) ze.getExtraField(X5455_ExtendedTimestamp.HEADER_ID);
assertNotNull(extendedTimestamp);
- assertEquals(TimeUtils.javaTimeToUnixTime(time), extendedTimestamp.getModifyTime().getValue());
assertEquals(TimeUtils.toUnixTime(accessTime), extendedTimestamp.getAccessTime().getValue());
assertEquals(TimeUtils.toUnixTime(creationTime), extendedTimestamp.getCreateTime().getValue());
X000A_NTFS ntfs = (X000A_NTFS) ze.getExtraField(X000A_NTFS.HEADER_ID);