org.eclipse.jgit.internal.storage.file

## Class LockFile

- java.lang.Object
- - org.eclipse.jgit.internal.storage.file.LockFile

    public class LockFile
    extends Object

Git style file locking and replacement.

To modify a ref file Git tries to use an atomic update approach: we write the new data into a brand new file, then rename it in place over the old name. This way we can just delete the temporary file if anything goes wrong, and nothing has been damaged. To coordinate access from multiple processes at once Git tries to atomically create the new temporary file under a well-known name.

### Constructor Summary

Constructors
Constructor and Description
`LockFile(File f, FS fs)` Create a new lock for any file.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`boolean` `commit()` Commit this change and release the lock.
`void` `copyCurrentContent()` Copy the current file content into the temporary file.
`void` `createCommitSnapshot()` Update the commit snapshot `getCommitSnapshot()` before commit.
`long` `getCommitLastModified()` Get the modification time of the output file when it was committed.
`FileSnapshot` `getCommitSnapshot()`
`OutputStream` `getOutputStream()` Obtain the direct output stream for this lock.
`boolean` `lock()` Try to establish the lock.
`boolean` `lockForAppend()` Try to establish the lock for appending.
`void` `setFSync(boolean on)` Request that `commit()` force dirty data to the drive.
`void` `setNeedSnapshot(boolean on)` Request that `commit()` remember the `FileSnapshot`.
`void` `setNeedStatInformation(boolean on)` Request that `commit()` remember modification time.
`String` `toString()`
`void` `unlock()` Unlock this file and abort this change.
`static boolean` `unlock(File file)` Unlock the given file.
`void` `waitForStatChange()` Wait until the lock file information differs from the old file.
`void` `write(byte[] content)` Write arbitrary data to the temporary file.
`void` `write(ObjectId id)` Write an ObjectId and LF to the temporary file.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### LockFile

    public LockFile(File f,
                    FS fs)

Create a new lock for any file.

Parameters:
  `f` - the file that will be locked.
  `fs` - the file system abstraction which will be necessary to perform certain file system operations.

### Method Detail

#### unlock

    public static boolean unlock(File file)

Unlock the given file.

This method can be used for recovering from a thrown `LockFailedException` . This method does not validate that the lock is or is not currently held before attempting to unlock it.

Parameters:
  `file` -
Returns:
  true if unlocked, false if unlocking failed

#### lock

    public boolean lock()
                 throws IOException

Try to establish the lock.

Returns:
  true if the lock is now held by the caller; false if it is held by someone else.
Throws:
  `IOException` - the temporary output file could not be created. The caller does not hold the lock.

#### lockForAppend

    public boolean lockForAppend()
                          throws IOException

Try to establish the lock for appending.

Returns:
  true if the lock is now held by the caller; false if it is held by someone else.
Throws:
  `IOException` - the temporary output file could not be created. The caller does not hold the lock.

#### copyCurrentContent

    public void copyCurrentContent()
                            throws IOException

Copy the current file content into the temporary file.

This method saves the current file content by inserting it into the temporary file, so that the caller can safely append rather than replace the primary file.

This method does nothing if the current file does not exist, or exists but is empty.

Throws:
  `IOException` - the temporary file could not be written, or a read error occurred while reading from the current file. The lock is released before throwing the underlying IO exception to the caller.
  `RuntimeException` - the temporary file could not be written. The lock is released before throwing the underlying exception to the caller.

#### write

    public void write(ObjectId id)
               throws IOException

Write an ObjectId and LF to the temporary file.

Parameters:
  `id` - the id to store in the file. The id will be written in hex, followed by a sole LF.
Throws:
  `IOException` - the temporary file could not be written. The lock is released before throwing the underlying IO exception to the caller.
  `RuntimeException` - the temporary file could not be written. The lock is released before throwing the underlying exception to the caller.

#### write

    public void write(byte[] content)
               throws IOException

Write arbitrary data to the temporary file.

Parameters:
  `content` - the bytes to store in the temporary file. No additional bytes are added, so if the file must end with an LF it must appear at the end of the byte array.
Throws:
  `IOException` - the temporary file could not be written. The lock is released before throwing the underlying IO exception to the caller.
  `RuntimeException` - the temporary file could not be written. The lock is released before throwing the underlying exception to the caller.

#### getOutputStream

    public OutputStream getOutputStream()

Obtain the direct output stream for this lock.

The stream may only be accessed once, and only after `lock()` has been successfully invoked and returned true. Callers must close the stream prior to calling `commit()` to commit the change.

Returns:
  a stream to write to the new file. The stream is unbuffered.

#### setNeedStatInformation

    public void setNeedStatInformation(boolean on)

Request that `commit()` remember modification time.

This is an alias for `setNeedSnapshot(true)`.

Parameters:
  `on` - true if the commit method must remember the modification time.

#### setNeedSnapshot

    public void setNeedSnapshot(boolean on)

Request that `commit()` remember the `FileSnapshot`.

Parameters:
  `on` - true if the commit method must remember the FileSnapshot.

#### setFSync

    public void setFSync(boolean on)

Request that `commit()` force dirty data to the drive.

Parameters:
  `on` - true if dirty data should be forced to the drive.

#### waitForStatChange

    public void waitForStatChange()
                           throws InterruptedException

Wait until the lock file information differs from the old file.

This method tests the last modification date. If both are the same, this method sleeps until it can force the new lock file's modification date to be later than the target file.

Throws:
  `InterruptedException` - the thread was interrupted before the last modified date of the lock file was different from the last modified date of the target file.

#### commit

    public boolean commit()

Commit this change and release the lock.

If this method fails (returns false) the lock is still released.

Returns:
  true if the commit was successful and the file contains the new data; false if the commit failed and the file remains with the old data.
Throws:
  `IllegalStateException` - the lock is not held.

#### getCommitLastModified

    public long getCommitLastModified()

Get the modification time of the output file when it was committed.

Returns:
  modification time of the lock file right before we committed it.

#### getCommitSnapshot

    public FileSnapshot getCommitSnapshot()

Returns:
  get the `FileSnapshot` just before commit.

#### createCommitSnapshot

    public void createCommitSnapshot()

Update the commit snapshot `getCommitSnapshot()` before commit.

This may be necessary if you need time stamp before commit occurs, e.g while writing the index.

#### unlock

    public void unlock()

Unlock this file and abort this change.

The temporary file (if created) is deleted before returning.

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`