Class FileSnapshot


  • public class FileSnapshot
    extends java.lang.Object
    A snapshot of file metadata that can be used to determine whether a file has been modified since the last time it was read. Intended usage:
     FileSnapshot fileSnapshot = FileSnapshot.save(path);
     byte[] content = Files.readAllBytes(path);
     ...
     FileSnapshot newSnapshot = oldSnapshot.reload(path);
     if (newSnapshot == fileSnapshot) {
       // File was not modified
     } else {
       // File may have been modified
       fileSnapshot = newSnapshot;
       content = Files.readAllBytes(path);
     }
     

    File modifications that occur quicker than the resolution of the system's "last modified" timestamp of a file cannot be detected reliably. This implementation assumes a worst-case filesystem timestamp resolution of 2 seconds (as it exists on FAT file systems). A snapshot taken within 2 seconds since the last modified time is considered "racily clean" only: the file will be considered potentially modified even if the metadata matches.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected FileSnapshot​(java.time.Instant snapTime, java.nio.file.attribute.FileTime lastModified, long size, java.lang.Object fileKey)
      Creates a new FileSnapshot instance.
    • Field Detail

      • UNKNOWN_SIZE

        public static final long UNKNOWN_SIZE
        A value indicating an unknown file size.
        See Also:
        Constant Field Values
      • WORST_CASE_TIMESTAMP_RESOLUTION

        private static final java.time.Duration WORST_CASE_TIMESTAMP_RESOLUTION
      • lastModified

        private final java.nio.file.attribute.FileTime lastModified
      • size

        private final long size
      • fileKey

        private final java.lang.Object fileKey
      • snapTime

        private final java.time.Instant snapTime
    • Constructor Detail

      • FileSnapshot

        protected FileSnapshot​(java.time.Instant snapTime,
                               java.nio.file.attribute.FileTime lastModified,
                               long size,
                               java.lang.Object fileKey)
        Creates a new FileSnapshot instance.
        Parameters:
        snapTime - the Instant the snapshot was taken
        lastModified - the "last modified" FileTime
        size - the file size
        fileKey - the file key
    • Method Detail

      • getLastModified

        protected java.nio.file.attribute.FileTime getLastModified()
        Retrieves the "last modified" time as recorded in this FileSnapshot.
        Returns:
        the FileTime, may be null
      • getSize

        protected long getSize()
        Retrieves the file size as recorded in this FileSnapshot.
        Returns:
        the size, UNKNOWN_SIZE for a snapshot of a non-existing file
      • getFileKey

        protected java.lang.Object getFileKey()
        Retrieves the file key as recorded in this FileSnapshot.
        Returns:
        the file key, may be null
      • getTime

        protected java.time.Instant getTime()
        Retrieves the time this FileSnapshot was taken.
        Returns:
        the Instant the snapshot was taken, never null
      • save

        public static FileSnapshot save​(java.nio.file.Path file,
                                        java.nio.file.LinkOption... options)
                                 throws java.io.IOException
        Creates a new FileSnapshot for the given path.
        Parameters:
        file - to take the snapshot of
        options - LinkOptions to use
        Returns:
        the FileSnapshot, never null
        Throws:
        java.io.IOException - if an I/O error occurs
      • reload

        public FileSnapshot reload​(java.nio.file.Path file,
                                   java.nio.file.LinkOption... options)
                            throws java.io.IOException
        Reload the FileSnapshot for the given file.
        Parameters:
        file - to take the snapshot of
        options - LinkOptions to use
        Returns:
        a FileSnapshot, never null; if == this, the file may be assumed unmodified
        Throws:
        java.io.IOException - if an I/O error occurs
      • mayBeRacilyClean

        protected boolean mayBeRacilyClean()
        Determines whether this FileSnapshot was taken within the file timestamp resolution of the file system after the last modified time of the file.
        Returns:
        true if so, false otherwise
      • same

        public boolean same​(FileSnapshot other)
        Compares the snapshots' file metadata.
        Parameters:
        other - FileSnapshot to compare to (should be for the same Path)
        Returns:
        true if the two snapshots have the same file metadata, false otherwise