Add FileTimes.isUnixTime(FileTime)

- Add FileTimes.isUnixTime(long)
- Add FileTimes.toUnixTime(FileTime)

Author: garydgregory

src/changes/changes.xml

@@ -86,6 +86,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add BoundedInputStream.getRemaining().</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add FileTimes.toNtfsTime(long).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add FileTimes.fromUnixTime(long).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add FileTimes.isUnixTime(FileTime).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add FileTimes.isUnixTime(long).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add FileTimes.toUnixTime(FileTime).</action>
       <!--  UPDATE -->
       <action dev="ggregory" type="fix"                due-to="Gary Gregory">Bump commons.bytebuddy.version from 1.14.10 to 1.14.11 #534.</action>
     </release>

src/main/java/org/apache/commons/io/file/attribute/FileTimes.java

@@ -72,6 +72,32 @@ public static FileTime fromUnixTime(final long time) {
         return FileTime.from(time, TimeUnit.SECONDS);
     }
 
+    /**
+     * Tests whether a FileTime can be safely represented in the standard UNIX time.
+     * <p>
+     * If the FileTime is null, this method 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.
+     * @since 2.16.0
+     */
+    public static boolean isUnixTime(final FileTime time) {
+        return isUnixTime(toUnixTime(time));
+    }
+
+    /**
+     * Tests whether a given number of seconds (since Epoch) can be safely represented in the standard UNIX time.
+     *
+     * @param seconds the number of seconds (since Epoch) to evaluate.
+     * @return true if the time can be represented in the standard UNIX time, false otherwise.
+     * @since 2.16.0
+     */
+    public static boolean isUnixTime(final long seconds) {
+        return Integer.MIN_VALUE <= seconds && seconds <= Integer.MAX_VALUE;
+    }
+
+
     /**
      * Subtracts milliseconds from a source FileTime.
      *
@@ -243,6 +269,21 @@ public static long toNtfsTime(final long javaTime) {
         return Math.subtractExact(javaHundredNanos, WINDOWS_EPOCH_OFFSET);
     }
 
+    /**
+     * Converts {@link FileTime} to standard UNIX time in seconds.
+     * <p>
+     * The returned seconds value may lie out of bounds of UNIX time. Check with {@link FileTimes#isUnixTime(long)}.
+     * </p>
+     *
+     * @param fileTime the original FileTime.
+     * @return the UNIX timestamp or 0 if the input is null.
+     * @see #isUnixTime(long)
+     * @since 2.16.0
+     */
+    public static long toUnixTime(final FileTime fileTime) {
+        return fileTime != null ? fileTime.to(TimeUnit.SECONDS) : 0;
+    }
+
     private FileTimes() {
         // No instances.
     }

src/test/java/org/apache/commons/io/file/attribute/FileTimesTest.java

@@ -19,6 +19,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.nio.file.attribute.FileTime;
 import java.time.Instant;
@@ -76,6 +77,18 @@ public static Stream<Arguments> fileTimeToNtfsProvider() {
         // @formatter:on
     }
 
+    public static Stream<Arguments> isUnixFileTimeProvider() {
+        // @formatter:off
+        return Stream.of(
+            Arguments.of("2022-12-27T12:45:22Z", true),
+            Arguments.of("2038-01-19T03:14:07Z", true),
+            Arguments.of("1901-12-13T23:14:08Z", true),
+            Arguments.of("1901-12-13T03:14:08Z", false),
+            Arguments.of("2038-01-19T03:14:08Z", false),
+            Arguments.of("2099-06-30T12:31:42Z", false));
+        // @formatter:on
+    }
+
     @ParameterizedTest
     @MethodSource("dateToNtfsProvider")
     public void testDateToFileTime(final String instant, final long ignored) {
@@ -115,15 +128,35 @@ public void testFileTimeToNtfsTime(final String instant, final long ntfsTime) {
         assertEquals(ntfsTime, FileTimes.toNtfsTime(parsed));
     }
 
-    //
-
     @ParameterizedTest
     @MethodSource("dateToNtfsProvider")
     public void testFromUnixTime(final String instant, final long ntfsTime) {
         final long epochSecond = Instant.parse(instant).getEpochSecond();
         assertEquals(epochSecond, FileTimes.fromUnixTime(epochSecond).to(TimeUnit.SECONDS));
     }
 
+    @ParameterizedTest
+    @MethodSource("isUnixFileTimeProvider")
+    public void testIsUnixTime(final String instant, final boolean isUnixTime) {
+        assertEquals(isUnixTime, FileTimes.isUnixTime(FileTime.from(Instant.parse(instant))));
+    }
+
+    @ParameterizedTest
+    @MethodSource("isUnixFileTimeProvider")
+    public void testIsUnixTimeLong(final String instant, final boolean isUnixTime) {
+        assertEquals(isUnixTime, FileTimes.isUnixTime(Instant.parse(instant).getEpochSecond()));
+    }
+
+    @ParameterizedTest
+    @MethodSource("isUnixFileTimeProvider")
+    public void testToUnixTime(final String instant, final boolean isUnixTime) {
+        assertEquals(isUnixTime, FileTimes.isUnixTime(FileTimes.toUnixTime(FileTime.from(Instant.parse(instant)))));
+    }
+
+    public void testIsUnixTimeFileTimeNull() {
+        assertTrue(FileTimes.isUnixTime(null));
+    }
+
     @Test
     public void testMinusMillis() {
         final int millis = 2;