com.sun.labs.minion.util
Class FileLock

java.lang.Object
  com.sun.labs.minion.util.FileLock

public class FileLock
extends java.lang.Object

Provides a class that locks a file so that only a single thread or process may access it. Note that all the classes have to try to get the lock, this is simply a synchronization tool and will not work if some threads or processes do not first try to acquire the lock.

The locking is done using Java NIO file locks. Such locks are VM-wide, so we need to be careful to ensure that the locks are also thread safe. To that end, the class stores a map of threads to the locks that they hold. Threads within a VM will synchronize on this map when acquiring, releasing or testing locks.

This, unfortunately, requires that multiple instances of this class that want to lock the same file must share the same map, otherwise the desired locking behavior will not work across the threads using the different instances. To that end, a copy constructor is provided that ensures that two locks for the same file share the same map, even if the number of retries and the sleep periods are different.

Field Summary

protected java.util.Map<java.lang.Thread,com.sun.labs.minion.util.FileLock.LockState>	lockState The thread local data for the state of the locks.
static java.lang.String	logTag

Constructor Summary

FileLock(java.io.File f)
Makes a lock that will retry the default number of times (30) and sleep the default amount of time between retries (150 milliseconds).

FileLock(java.io.File dir, java.io.File f)
Makes a lock that will retry the default number of times (30) and sleep the default amount of time between retries (150 milliseconds).

FileLock(java.io.File dir, java.io.File f, long timeout, java.util.concurrent.TimeUnit units)
Creates a lock for a file in a given directory.

FileLock(FileLock l, long timeout, java.util.concurrent.TimeUnit units)
Creates a lock that's a copy of the given lock, except the timeout may differ.

FileLock(java.io.File f, long timeout, java.util.concurrent.TimeUnit units)
Creates a lock for a file in the current directory.

Method Summary

void	acquireLock() Acquires the lock on the file.
boolean	hasLock() Tells us whether we currently hold a lock on the file.
boolean	hasLock(java.lang.Thread t) Tells us whether the given thread has a lock on the file.
void	releaseLock() Release the lock on the file, if the calling thread currently holds it.
java.lang.String	toString() Gets a string describing the lock.
void	tradeLock(java.lang.Thread owner, java.lang.Thread taker) Trades the lock from one thread to another.

Methods inherited from class java.lang.Object

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

Field Detail

logTag

public static final java.lang.String logTag

See Also:

Constant Field Values

lockState

protected java.util.Map<java.lang.Thread,com.sun.labs.minion.util.FileLock.LockState> lockState

The thread local data for the state of the locks.

Constructor Detail

FileLock

public FileLock(java.io.File dir,
                java.io.File f)

Makes a lock that will retry the default number of times (30) and sleep the default amount of time between retries (150 milliseconds). This does not lock the file. Use the acquireLock method for that.

Parameters:

dir - The directory where the lock should reside.

f - The file that we want to lock.

See Also:

acquireLock()

FileLock

public FileLock(java.io.File f)

Makes a lock that will retry the default number of times (30) and sleep the default amount of time between retries (150 milliseconds). This does not lock the file. Use the acquireLock method for that.

Parameters:

f - The File that we want to lock.

See Also:

acquireLock()

FileLock

public FileLock(java.io.File f,
                long timeout,
                java.util.concurrent.TimeUnit units)

Creates a lock for a file in the current directory.

Parameters:

f - the name of the file to lock

timeout - the timeout to use when trying to acquire the lock

units - the units for the timeout. This will be converted to milliseconds, so beware of truncation!

FileLock

public FileLock(java.io.File dir,
                java.io.File f,
                long timeout,
                java.util.concurrent.TimeUnit units)

Creates a lock for a file in a given directory.

Parameters:

dir - the directory where the lock file should be created. If this is null, the current working directory will be used

f - the name of the file to lock

timeout - the timeout to use when trying to acquire the lock

units - the units for the timeout. This will be converted to milliseconds, so beware of truncation!

FileLock

public FileLock(FileLock l,
                long timeout,
                java.util.concurrent.TimeUnit units)

Creates a lock that's a copy of the given lock, except the timeout may differ. The two locks will share the lock state so that multiple threads will not be able to hold concurrent locks, but single threads will.

Parameters:

l - the lock that we want to copy attempts to get the lock.

timeout - the timeout to use when trying to acquire the lock

units - the units for the timeout. This will be converted to milliseconds, so beware of truncation!

Method Detail

acquireLock

public void acquireLock()
                 throws java.io.IOException,
                        FileLockException

Acquires the lock on the file. This code will try repeatedly to acquire the lock.

Throws:

FileLockException - when the lock cannot be acquired within the specified parameters.

java.io.IOException - if there is an I/O error while obtaining the lock

releaseLock

public void releaseLock()
                 throws FileLockException

Release the lock on the file, if the calling thread currently holds it. This is accomplished by deleting our lock file.

Throws:

FileLockException - when the lock cannot be released.

tradeLock

public void tradeLock(java.lang.Thread owner,
                      java.lang.Thread taker)
               throws FileLockException

Trades the lock from one thread to another.

Parameters:

owner - The owner of the lock.

taker - The thread taking the locking.

Throws:

FileLockException - If there is an error trading the lock.

hasLock

public boolean hasLock(java.lang.Thread t)

Tells us whether the given thread has a lock on the file.

Parameters:

t - The thread.

Returns:

true if the given thread has the lock, false otherwise.

hasLock

public boolean hasLock()

Tells us whether we currently hold a lock on the file.

Returns:

true if the current thread holds the lock, false otherwise.

toString

public java.lang.String toString()

Gets a string describing the lock.

Overrides:

toString in class java.lang.Object

Returns:

A string describing the lock.