org.eclipse.jgit.storage.file
Class LockFile

java.lang.Object
  org.eclipse.jgit.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

LockFile(File f, FS fs)
Create a new lock for any file.

Method Summary

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