co.codewizards.cloudstore.core.io

Interface LockFile

All Superinterfaces:

AutoCloseable

public interface LockFile
extends AutoCloseable

Lock-file exclusively locking a certain file.

An instance is acquired by invoking LockFileFactory.acquire(File, long).

All methods of this interface are thread-safe.

Important: You should never access the locked file directly. Though this works fine on some operating systems (e.g. on GNU/Linux), it fails on others (e.g. on Windows). If you want to read from / write to the locked file, please use createInputStream() or createOutputStream() instead.

Author:

Marco หงุ่ยตระกูล-Schulze - marco at codewizards dot co

Method Summary

Modifier and Type	Method and Description
void	close() Equivalent to release().
IInputStream	createInputStream() Creates an InputStream reading from the locked file.
IOutputStream	createOutputStream() Creates an OutputStream writing into the locked file (overwriting all old content).
File	getFile() Gets the underlying file being locked.
Lock	getLock() Gets the Lock corresponding to the underlying file to synchronise multiple threads of the same process.
void	release() Releases the lock.

Method Detail

getFile

File getFile()

Gets the underlying file being locked.

Returns:

the underlying file being locked. Never null.

release

void release()

Releases the lock.

Important: This method must be called exactly once for every LockFile instance! It is highly recommended to use a try-finally-block:

  LockFile lockFile = LockFileFactory.acquire(theFile, theTimeout);
  try {
    // do something
  } finally {
    lockFile.release();
  }

This method is thread-safe and thus might be invoked on a different thread than the instance was created. However, it should be invoked exactly once (per LockFile instance).

Please note: It is possible to use the new try-with-resources-clause introduced by Java 7. See close().

See Also:

LockFileFactory.acquire(File, long), close()

close

void close()

Equivalent to release().

Implementations must make sure that invoking close() means exactly the same as invoking release(). This method was added to make the usage of LockFile possible in a try-with-resources-clause. See AutoCloseable for more details. Here's a code example:

  try ( LockFile lockFile = LockFileFactory.acquire(theFile, theTimeout); ) {
    // do something while the file represented by 'lockFile' is locked.
  }

Specified by:

close in interface AutoCloseable

See Also:

release()

getLock

Lock getLock()

Gets the Lock corresponding to the underlying file to synchronise multiple threads of the same process.

A LockFile (usually implemented using FileLock) is not guaranteed to exclude multiple threads from accessing a single file. In order to additionally provide thread-synchronisation (as is pretty straight-forward and needed in many situations), there is a Lock associated to every LockFile. It is highly recommended to synchronise additionally on this Lock. Note, that createInputStream() and createOutputStream() are expected to implicitly do this.

Returns:

the Lock corresponding to the underlying file. Never null.

createInputStream

IInputStream createInputStream()
                        throws IOException

Creates an InputStream reading from the locked file.

Important: You must close the InputStream! Locks held are released only when doing so.

Returns:

an InputStream reading from the locked file. Never null.

Throws:

IOException - if creating the InputStream fails.

createOutputStream

IOutputStream createOutputStream()
                          throws IOException

Creates an OutputStream writing into the locked file (overwriting all old content).

Important: You must close the OutputStream! Locks held are released only when doing so.

Returns:

an OutputStream writing into the locked file. Never null.

Throws:

IOException - if creating the OutputStream fails.