Module org.eclipse.jgit
Package 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
    Description
    static final FileSnapshot
    DIRTY
    A FileSnapshot that is considered to always be modified.
    static final FileSnapshot
    MISSING_FILE
    A FileSnapshot that is clean if the file does not exist.
    static final long
    UNKNOWN_SIZE
    An unknown file size.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    FileSnapshot(File file)
    Record a snapshot for a specific file path.
    protected
    FileSnapshot(File file, boolean useConfig)
    Record a snapshot for a specific file path.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object obj)
     
    boolean
    equals(FileSnapshot other)
    Compare two snapshots to see if they cache the same information.
    int
    hashCode()
     
    boolean
    isModified(File path)
    Check if the path may have been modified since the snapshot was saved.
    long
    lastDelta()
    Get the delta in nanoseconds between lastModified and lastRead during last racy check
    Instant
    lastModifiedInstant()
    Get time of last snapshot update
    long
    lastRacyThreshold()
    Get the racyLimitNanos threshold in nanoseconds during last racy check
    static FileSnapshot
    save(File path)
    Record a snapshot for a specific file path.
    static FileSnapshot
    save(Instant modified)
    Record a snapshot for a file for which the last modification time is already known.
    static FileSnapshot
    saveNoConfig(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()
    Get file size in bytes of last snapshot update
    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 Details

    • 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:

    • 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 Details

    • FileSnapshot

      protected FileSnapshot(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(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 - if true read filesystem time resolution from configuration file otherwise use fallback resolution

  • Method Details

    • 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.

    • saveNoConfig

      public static FileSnapshot saveNoConfig(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.

    • save

      public static FileSnapshot save(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.

    • lastModifiedInstant

      public Instant lastModifiedInstant()
      Get time of last snapshot update
      Returns:
      time of last snapshot update

    • size

      public long size()
      Get file size in bytes of last snapshot update
      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

    • lastDelta

      public long lastDelta()
      Get the delta in nanoseconds between lastModified and lastRead during last racy check
      Returns:
      the delta in nanoseconds between lastModified and lastRead during last racy check

    • lastRacyThreshold

      public long lastRacyThreshold()
      Get the racyLimitNanos threshold in nanoseconds during last racy check
      Returns:
      the racyLimitNanos threshold in nanoseconds during last racy check

    • toString

      public String toString()
      Overrides:
      toString in class Object