Package org.apache.sshd.common.util.io

Class FileSnapshot

java.lang.Object

org.apache.sshd.common.util.io.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.

Field Summary

Fields

Modifier and Type	Field	Description
private java.lang.Object	fileKey
private java.nio.file.attribute.FileTime	lastModified
static FileSnapshot	NO_FILE	A FileSnapshot describing a non-existing file.
private long	size
private java.time.Instant	snapTime
static long	UNKNOWN_SIZE	A value indicating an unknown file size.
private static java.time.Duration	WORST_CASE_TIMESTAMP_RESOLUTION

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.

Method Summary

Modifier and Type	Method	Description
protected java.lang.Object	getFileKey()	Retrieves the file key as recorded in this FileSnapshot.
protected java.nio.file.attribute.FileTime	getLastModified()	Retrieves the "last modified" time as recorded in this FileSnapshot.
protected long	getSize()	Retrieves the file size as recorded in this FileSnapshot.
protected java.time.Instant	getTime()	Retrieves the time this FileSnapshot was taken.
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.
FileSnapshot	reload(java.nio.file.Path file, java.nio.file.LinkOption... options)	Reload the FileSnapshot for the given file.
boolean	same(FileSnapshot other)	Compares the snapshots' file metadata.
static FileSnapshot	save(java.nio.file.Path file, java.nio.file.LinkOption... options)	Creates a new FileSnapshot for the given path.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNKNOWN_SIZE

public static final long UNKNOWN_SIZE

A value indicating an unknown file size.

See Also:

Constant Field Values

NO_FILE

public static final FileSnapshot NO_FILE

A FileSnapshot describing a non-existing file.

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