Add AgeFileFilter.AgeFileFilter(Instant, boolean)

- Add PathUtils.isNewer(Path, Instant, LinkOption...)
- Add PathUtils.isNewer(Path, FileTime, LinkOption...).

Author: garydgregory

src/changes/changes.xml

@@ -147,6 +147,15 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add FileSystem.normalizeSeparators().
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add PathUtils.isNewer(Path, FileTime, LinkOption...).
+      </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add PathUtils.isNewer(Path, Instant, LinkOption...).
+      </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add AgeFileFilter.AgeFileFilter(Instant, boolean).
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Dependabot">
         Bump Maven Javadoc plugin from 3.2.0 to 3.3.0.

src/main/java/org/apache/commons/io/file/PathUtils.java

@@ -43,9 +43,11 @@
 import java.nio.file.attribute.BasicFileAttributes;
 import java.nio.file.attribute.DosFileAttributeView;
 import java.nio.file.attribute.FileAttribute;
+import java.nio.file.attribute.FileTime;
 import java.nio.file.attribute.PosixFileAttributeView;
 import java.nio.file.attribute.PosixFileAttributes;
 import java.nio.file.attribute.PosixFilePermission;
+import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
@@ -766,20 +768,56 @@ public static boolean isEmptyFile(final Path file) throws IOException {
      * Tests if the specified {@code Path} is newer than the specified time reference.
      *
      * @param file the {@code Path} of which the modification date must be compared
-     * @param timeMillis the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
+     * @param fileTime the time reference.
      * @param options options indicating how symbolic links are handled * @return true if the {@code Path} exists and has
      *        been modified after the given time reference.
      * @return true if the {@code Path} exists and has been modified after the given time reference.
      * @throws IOException if an I/O error occurs.
      * @throws NullPointerException if the file is {@code null}
-     * @since 2.9.0
+     * @since 2.12.0
      */
-    public static boolean isNewer(final Path file, final long timeMillis, final LinkOption... options) throws IOException {
+    public static boolean isNewer(final Path file, final FileTime fileTime, final LinkOption... options) throws IOException {
+        Objects.requireNonNull(file, "file");
+        if (Files.notExists(file)) {
+            return false;
+        }
+        return Files.getLastModifiedTime(file, options).compareTo(fileTime) > 0;
+    }
+
+    /**
+     * Tests if the specified {@code Path} is newer than the specified time reference.
+     *
+     * @param file the {@code Path} of which the modification date must be compared
+     * @param instant the time reference.
+     * @param options options indicating how symbolic links are handled * @return true if the {@code Path} exists and has
+     *        been modified after the given time reference.
+     * @return true if the {@code Path} exists and has been modified after the given time reference.
+     * @throws IOException if an I/O error occurs.
+     * @throws NullPointerException if the file is {@code null}
+     * @since 2.12.0
+     */
+    public static boolean isNewer(final Path file, final Instant instant, final LinkOption... options) throws IOException {
         Objects.requireNonNull(file, "file");
         if (Files.notExists(file)) {
             return false;
         }
-        return Files.getLastModifiedTime(file, options).toMillis() > timeMillis;
+        return Files.getLastModifiedTime(file, options).toInstant().isAfter(instant);
+    }
+
+    /**
+     * Tests if the specified {@code Path} is newer than the specified time reference.
+     *
+     * @param file the {@code Path} of which the modification date must be compared
+     * @param timeMillis the time reference measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
+     * @param options options indicating how symbolic links are handled * @return true if the {@code Path} exists and has
+     *        been modified after the given time reference.
+     * @return true if the {@code Path} exists and has been modified after the given time reference.
+     * @throws IOException if an I/O error occurs.
+     * @throws NullPointerException if the file is {@code null}
+     * @since 2.9.0
+     */
+    public static boolean isNewer(final Path file, final long timeMillis, final LinkOption... options) throws IOException {
+        return isNewer(file, FileTime.fromMillis(timeMillis), options);
     }
 
     /**

src/main/java/org/apache/commons/io/filefilter/AgeFileFilter.java

@@ -22,6 +22,7 @@
 import java.nio.file.FileVisitResult;
 import java.nio.file.Path;
 import java.nio.file.attribute.BasicFileAttributes;
+import java.time.Instant;
 import java.util.Date;
 
 import org.apache.commons.io.FileUtils;
@@ -80,7 +81,7 @@ public class AgeFileFilter extends AbstractFileFilter implements Serializable {
     private final boolean acceptOlder;
 
     /** The cutoff time threshold measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970). */
-    private final long cutoffMillis;
+    private final Instant cutoffInstant;
 
     /**
      * Constructs a new age file filter for files older than (at or before) a certain cutoff date.
@@ -124,6 +125,20 @@ public AgeFileFilter(final File cutoffReference, final boolean acceptOlder) {
         this(FileUtils.lastModifiedUnchecked(cutoffReference), acceptOlder);
     }
 
+    /**
+     * Constructs a new age file filter for files on any one side of a certain cutoff.
+     *
+     * @param cutoffInstant The cutoff time threshold since the epoch (00:00:00 GMT, January 1,
+     *        1970).
+     * @param acceptOlder if true, older files (at or before the cutoff) are accepted, else newer ones (after the
+     *        cutoff).
+     * @since 2.12.0
+     */
+    public AgeFileFilter(final Instant cutoffInstant, final boolean acceptOlder) {
+        this.acceptOlder = acceptOlder;
+        this.cutoffInstant = cutoffInstant;
+    }
+
     /**
      * Constructs a new age file filter for files equal to or older than a certain cutoff
      *
@@ -143,8 +158,7 @@ public AgeFileFilter(final long cutoffMillis) {
      *        cutoff).
      */
     public AgeFileFilter(final long cutoffMillis, final boolean acceptOlder) {
-        this.acceptOlder = acceptOlder;
-        this.cutoffMillis = cutoffMillis;
+        this(Instant.ofEpochMilli(cutoffMillis), acceptOlder);
     }
 
     /**
@@ -159,7 +173,7 @@ public AgeFileFilter(final long cutoffMillis, final boolean acceptOlder) {
      */
     @Override
     public boolean accept(final File file) {
-        final boolean newer = FileUtils.isFileNewer(file, cutoffMillis);
+        final boolean newer = FileUtils.isFileNewer(file, cutoffInstant);
         return acceptOlder != newer;
     }
 
@@ -178,7 +192,7 @@ public boolean accept(final File file) {
     public FileVisitResult accept(final Path file, final BasicFileAttributes attributes) {
         final boolean newer;
         try {
-            newer = PathUtils.isNewer(file, cutoffMillis);
+            newer = PathUtils.isNewer(file, cutoffInstant);
         } catch (final IOException e) {
             return handle(e);
         }
@@ -193,6 +207,6 @@ public FileVisitResult accept(final Path file, final BasicFileAttributes attribu
     @Override
     public String toString() {
         final String condition = acceptOlder ? "<=" : ">";
-        return super.toString() + "(" + condition + cutoffMillis + ")";
+        return super.toString() + "(" + condition + cutoffInstant + ")";
     }
 }

src/main/java/org/apache/commons/io/filefilter/FileFilterUtils.java

@@ -111,26 +111,26 @@ public static IOFileFilter ageFileFilter(final File cutoffReference, final boole
      * Returns a filter that returns true if the file was last modified before
      * or at the specified cutoff time.
      *
-     * @param cutoff  the time threshold
+     * @param cutoffMillis  the time threshold
      * @return an appropriately configured age file filter
      * @see AgeFileFilter
      * @since 1.2
      */
-    public static IOFileFilter ageFileFilter(final long cutoff) {
-        return new AgeFileFilter(cutoff);
+    public static IOFileFilter ageFileFilter(final long cutoffMillis) {
+        return new AgeFileFilter(cutoffMillis);
     }
 
     /**
      * Returns a filter that filters files based on a cutoff time.
      *
-     * @param cutoff  the time threshold
+     * @param cutoffMillis  the time threshold
      * @param acceptOlder  if true, older files get accepted, if false, newer
      * @return an appropriately configured age file filter
      * @see AgeFileFilter
      * @since 1.2
      */
-    public static IOFileFilter ageFileFilter(final long cutoff, final boolean acceptOlder) {
-        return new AgeFileFilter(cutoff, acceptOlder);
+    public static IOFileFilter ageFileFilter(final long cutoffMillis, final boolean acceptOlder) {
+        return new AgeFileFilter(cutoffMillis, acceptOlder);
     }
 
     /**