org.apache.commons.transaction.locking
Interface LockManager<K,M>

All Known Subinterfaces:

HierarchicalLockManager<K,M>

All Known Implementing Classes:

AbstractLockManager, DefaultHierarchicalLockManager, RWLockManager, SimpleLockManager

public interface LockManager<K,M>

Main interface to acquire and manage locks.

The idea is that a block of work is done between the calls of startWork(long, TimeUnit) and endWork(). Each resource touched can be locked either by lock(Object, Object, boolean) or tryLock(Object, Object, boolean). In case the timeout given in startWork(long, TimeUnit) is exceeded locking requests are terminated with a LockException. Finally, endWork() releases all locks in a bulk.

The benefit of such an implementation is that you can no longer forget to release locks that would otherwise lurk around forever. Additionally, as there is a central manager for all locks implementations can perform additional checks like, for example, a deadlock detection.

Implementations are free to decide whether they want to make use of the exclusive flag passed in lock(Object, Object, boolean) and tryLock(Object, Object, boolean).

You can plug in your own lock manager version most easily. However, for advanced features this will most likely require a custom implementation of Lock as well.

See Also:

RWLockManager, HierarchicalLockManager, DefaultHierarchicalLockManager, AbstractLockManager, SimpleLockManager

Method Summary

void	endWork() Ends a block of work that has been started in startWork(long, TimeUnit).
void	lock(M resourceManager, K key, boolean exclusive) Locks a resource denoted by a key and a resource manager.
void	startWork(long timeout, TimeUnit unit) Starts a block of work for which a certain set of locks is required.
boolean	tryLock(M resourceManager, K key, boolean exclusive) Tries to acquire a lock on a resource denoted by a key and a resource manager.

Method Detail

startWork

void startWork(long timeout,
               TimeUnit unit)

Starts a block of work for which a certain set of locks is required.

Parameters:

timeout - the maximum time for the whole work to take before it times out

unit - the time unit of the timeout argument

endWork

void endWork()

Ends a block of work that has been started in startWork(long, TimeUnit). All locks acquired will be released. All registered locks will be unregistered from this lock manager.

lock

void lock(M resourceManager,
          K key,
          boolean exclusive)
          throws LockException

Locks a resource denoted by a key and a resource manager.

Parameters:

resourceManager - resource manager that tries to acquire a lock

key - the key for the resource to be locked

exclusive - true if this lock shall be acquired in exclusive mode, false if it can be shared by other threads

Throws:

LockException - if the lock could not be acquired, possibly because of a timeout or a deadlock

tryLock

boolean tryLock(M resourceManager,
                K key,
                boolean exclusive)

Tries to acquire a lock on a resource denoted by a key and a resource manager.

Parameters:

resourceManager - resource manager that tries to acquire a lock

key - the key for the resource to be locked

exclusive - true if this lock shall be acquired in exclusive mode, false if it can be shared by other threads

Returns:

true if the lock was acquired, false otherwise