org.eclipse.jgit.internal.storage.file

Class FileSnapshot

java.lang.Object

org.eclipse.jgit.internal.storage.file.FileSnapshot

public class FileSnapshot
extends Object

Caches when a file was last read, making it possible to detect future edits.

This object tracks the last modified time of a file. Later during an invocation of isModified(File) the object will return true if the file may have been modified and should be re-read from disk.

A snapshot does not "live update" when the underlying filesystem changes. Callers must poll for updates by periodically invoking isModified(File).

To work around the "racy git" problem (where a file may be modified multiple times within the granularity of the filesystem modification clock) this class may return true from isModified(File) if the last modification time of the file is less than 3 seconds ago.

Field Summary

Fields

Modifier and Type	Field and Description
static FileSnapshot	DIRTY A FileSnapshot that is considered to always be modified.
static FileSnapshot	MISSING_FILE A FileSnapshot that is clean if the file does not exist.
static long	UNKNOWN_SIZE An unknown file size.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FileSnapshot(File path) Record a snapshot for a specific file path.

Method Summary

Modifier and Type	Method and Description
boolean	equals(FileSnapshot other) Compare two snapshots to see if they cache the same information.
boolean	equals(Object obj)
int	hashCode()
boolean	isModified(File path) Check if the path may have been modified since the snapshot was saved.
long	lastModified() Get time of last snapshot update
static FileSnapshot	save(File path) Record a snapshot for a specific file path.
static FileSnapshot	save(long modified) Record a snapshot for a file for which the last modification time is already known.
void	setClean(FileSnapshot other) Update this snapshot when the content hasn't changed.
long	size()
String	toString()
void	waitUntilNotRacy() Wait until this snapshot's file can't be racy anymore

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNKNOWN_SIZE

public static final long UNKNOWN_SIZE

An unknown file size. This value is used when a comparison needs to happen purely on the lastUpdate.

See Also:

Constant Field Values

DIRTY

public static final FileSnapshot DIRTY

A FileSnapshot that is considered to always be modified.

This instance is useful for application code that wants to lazily read a file, but only after isModified(File) gets invoked. The returned snapshot contains only invalid status information.

MISSING_FILE

public static final FileSnapshot MISSING_FILE

A FileSnapshot that is clean if the file does not exist.

This instance is useful if the application wants to consider a missing file to be clean. isModified(File) will return false if the file path does not exist.

Constructor Detail

FileSnapshot

protected FileSnapshot(File path)

Record a snapshot for a specific file path.

This method should be invoked before the file is accessed.

Parameters:

path - the path to later remember. The path's current status information is saved.

Method Detail

save

public static FileSnapshot save(File path)

Record a snapshot for a specific file path.

This method should be invoked before the file is accessed.

Parameters:

path - the path to later remember. The path's current status information is saved.

Returns:

the snapshot.

save

public static FileSnapshot save(long modified)

Record a snapshot for a file for which the last modification time is already known.

This method should be invoked before the file is accessed.

Note that this method cannot rely on measuring file timestamp resolution to avoid racy git issues caused by finite file timestamp resolution since it's unknown in which filesystem the file is located. Hence the worst case fallback for timestamp resolution is used.

Parameters:

modified - the last modification time of the file

Returns:

the snapshot.

lastModified

public long lastModified()

Get time of last snapshot update

Returns:

time of last snapshot update

size

public long size()

Returns:

file size in bytes of last snapshot update

isModified

public boolean isModified(File path)

Check if the path may have been modified since the snapshot was saved.

Parameters:

path - the path the snapshot describes.

Returns:

true if the path needs to be read again.

setClean

public void setClean(FileSnapshot other)

Update this snapshot when the content hasn't changed.

If the caller gets true from isModified(File), re-reads the content, discovers the content is identical, and equals(FileSnapshot) is true, it can use setClean(FileSnapshot) to make a future isModified(File) return false. The logic goes something like this:

 if (snapshot.isModified(path)) {
  FileSnapshot other = FileSnapshot.save(path);
  Content newContent = ...;
  if (oldContent.equals(newContent) && snapshot.equals(other))
      snapshot.setClean(other);
 }
 

Parameters:

other - the other snapshot.

waitUntilNotRacy

public void waitUntilNotRacy()
                      throws InterruptedException

Wait until this snapshot's file can't be racy anymore

Throws:

InterruptedException - if sleep was interrupted

equals

public boolean equals(FileSnapshot other)

Compare two snapshots to see if they cache the same information.

Parameters:

other - the other snapshot.

Returns:

true if the two snapshots share the same information.

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object