Class FileSnapshot
- java.lang.Object
-
- org.eclipse.jgit.internal.storage.file.FileSnapshot
-
- Direct Known Subclasses:
PackFileSnapshot
public class FileSnapshot extends java.lang.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 Description private boolean
cannotBeRacilyClean
True oncelastRead
is far later thanlastModified
.private static java.time.format.DateTimeFormatter
dateFmt
private long
delta
static FileSnapshot
DIRTY
A FileSnapshot that is considered to always be modified.private java.io.File
file
private java.lang.Object
fileKey
Object that uniquely identifies the given file, ornull
if a file key is not availableprivate boolean
fileKeyChanged
private FS.FileStoreAttributes
fileStoreAttributeCache
measured FileStore attributesprivate java.time.Instant
lastModified
Last observed modification time of the path.private boolean
lastModifiedChanged
private java.time.Instant
lastRead
Last wall-clock time the path was read.private static org.slf4j.Logger
LOG
static FileSnapshot
MISSING_FILE
A FileSnapshot that is clean if the file does not exist.private static java.lang.Object
MISSING_FILEKEY
private long
racyThreshold
private long
size
Underlying file-system size in bytes.private boolean
sizeChanged
static long
UNKNOWN_SIZE
An unknown file size.private static java.time.Instant
UNKNOWN_TIME
private boolean
wasRacyClean
-
Constructor Summary
Constructors Modifier Constructor Description protected
FileSnapshot(java.io.File file)
Record a snapshot for a specific file path.protected
FileSnapshot(java.io.File file, boolean useConfig)
Record a snapshot for a specific file path.private
FileSnapshot(java.time.Instant read, java.time.Instant modified, long size, java.time.Duration fsTimestampResolution, java.lang.Object fileKey)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
equals(java.lang.Object obj)
boolean
equals(FileSnapshot other)
Compare two snapshots to see if they cache the same information.private long
getEffectiveRacyThreshold()
private static java.lang.Object
getFileKey(java.nio.file.attribute.BasicFileAttributes fileAttributes)
int
hashCode()
private boolean
isFileKeyChanged(java.lang.Object currFileKey)
boolean
isModified(java.io.File path)
Check if the path may have been modified since the snapshot was saved.private boolean
isModified(java.time.Instant currLastModified)
private boolean
isRacyClean(java.time.Instant read)
private boolean
isSizeChanged(long currSize)
long
lastDelta()
long
lastModified()
Deprecated.uselastModifiedInstant()
insteadjava.time.Instant
lastModifiedInstant()
Get time of last snapshot updatelong
lastRacyThreshold()
static FileSnapshot
save(long modified)
Deprecated.usesave(Instant)
instead.static FileSnapshot
save(java.io.File path)
Record a snapshot for a specific file path.static FileSnapshot
save(java.time.Instant modified)
Record a snapshot for a file for which the last modification time is already known.static FileSnapshot
saveNoConfig(java.io.File path)
Record a snapshot for a specific file path without using config file to get filesystem timestamp resolution.void
setClean(FileSnapshot other)
Update this snapshot when the content hasn't changed.long
size()
java.lang.String
toString()
void
waitUntilNotRacy()
Wait until this snapshot's file can't be racy anymore(package private) boolean
wasFileKeyChanged()
(package private) boolean
wasLastModifiedChanged()
(package private) boolean
wasLastModifiedRacilyClean()
(package private) boolean
wasSizeChanged()
-
-
-
Field Detail
-
LOG
private static final org.slf4j.Logger LOG
-
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
-
UNKNOWN_TIME
private static final java.time.Instant UNKNOWN_TIME
-
MISSING_FILEKEY
private static final java.lang.Object MISSING_FILEKEY
-
dateFmt
private static final java.time.format.DateTimeFormatter dateFmt
-
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.
-
lastModified
private final java.time.Instant lastModified
Last observed modification time of the path.
-
lastRead
private volatile java.time.Instant lastRead
Last wall-clock time the path was read.
-
cannotBeRacilyClean
private boolean cannotBeRacilyClean
True oncelastRead
is far later thanlastModified
.
-
size
private final long size
Underlying file-system size in bytes. When set toUNKNOWN_SIZE
the size is not considered for modification checks.
-
fileStoreAttributeCache
private FS.FileStoreAttributes fileStoreAttributeCache
measured FileStore attributes
-
fileKey
private final java.lang.Object fileKey
Object that uniquely identifies the given file, ornull
if a file key is not available
-
file
private final java.io.File file
-
sizeChanged
private boolean sizeChanged
-
fileKeyChanged
private boolean fileKeyChanged
-
lastModifiedChanged
private boolean lastModifiedChanged
-
wasRacyClean
private boolean wasRacyClean
-
delta
private long delta
-
racyThreshold
private long racyThreshold
-
-
Constructor Detail
-
FileSnapshot
protected FileSnapshot(java.io.File file)
Record a snapshot for a specific file path.This method should be invoked before the file is accessed.
- Parameters:
file
- the path to remember meta data for. The path's current status information is saved.
-
FileSnapshot
protected FileSnapshot(java.io.File file, boolean useConfig)
Record a snapshot for a specific file path.This method should be invoked before the file is accessed.
- Parameters:
file
- the path to remember meta data for. The path's current status information is saved.useConfig
- iftrue
read filesystem time resolution from configuration file otherwise use fallback resolution
-
-
Method Detail
-
save
public static FileSnapshot save(java.io.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.
-
saveNoConfig
public static FileSnapshot saveNoConfig(java.io.File path)
Record a snapshot for a specific file path without using config file to get filesystem timestamp resolution.This method should be invoked before the file is accessed. It is used by FileBasedConfig to avoid endless recursion.
- Parameters:
path
- the path to later remember. The path's current status information is saved.- Returns:
- the snapshot.
-
getFileKey
private static java.lang.Object getFileKey(java.nio.file.attribute.BasicFileAttributes fileAttributes)
-
save
@Deprecated public static FileSnapshot save(long modified)
Deprecated.usesave(Instant)
instead.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.
-
save
public static FileSnapshot save(java.time.Instant 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
@Deprecated public long lastModified()
Deprecated.uselastModifiedInstant()
insteadGet time of last snapshot update- Returns:
- time of last snapshot update
-
lastModifiedInstant
public java.time.Instant lastModifiedInstant()
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(java.io.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, andequals(FileSnapshot)
is true, it can usesetClean(FileSnapshot)
to make a futureisModified(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 java.lang.InterruptedException
Wait until this snapshot's file can't be racy anymore- Throws:
java.lang.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(java.lang.Object obj)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
wasSizeChanged
boolean wasSizeChanged()
- Returns:
true
if FileSnapshot.isModified(File) found the file size changed
-
wasFileKeyChanged
boolean wasFileKeyChanged()
- Returns:
true
if FileSnapshot.isModified(File) found the file key changed
-
wasLastModifiedChanged
boolean wasLastModifiedChanged()
- Returns:
true
if FileSnapshot.isModified(File) found the file's lastModified changed
-
wasLastModifiedRacilyClean
boolean wasLastModifiedRacilyClean()
- Returns:
true
if FileSnapshot.isModified(File) detected that lastModified is racily clean
-
lastDelta
public long lastDelta()
- Returns:
- the delta in nanoseconds between lastModified and lastRead during last racy check
-
lastRacyThreshold
public long lastRacyThreshold()
- Returns:
- the racyLimitNanos threshold in nanoseconds during last racy check
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
isRacyClean
private boolean isRacyClean(java.time.Instant read)
-
getEffectiveRacyThreshold
private long getEffectiveRacyThreshold()
-
isModified
private boolean isModified(java.time.Instant currLastModified)
-
isFileKeyChanged
private boolean isFileKeyChanged(java.lang.Object currFileKey)
-
isSizeChanged
private boolean isSizeChanged(long currSize)
-
-