org.apache.commons.transaction.locking
Class ReadWriteUpgradeLock

java.lang.Object
  extended by org.apache.commons.transaction.locking.GenericLock
      extended by org.apache.commons.transaction.locking.ReadWriteUpgradeLock
All Implemented Interfaces:
MultiLevelLock, MultiLevelLock2

public class ReadWriteUpgradeLock
extends GenericLock

Convenience implementation of a read/write lock with an option for upgrade based on ReadWriteUpgradeLockLock.

Reads are shared which means there can be any number of concurrent read accesses allowed by this lock. Writes are exclusive. This means when there is a write access no other access neither read nor write are allowed by this lock.

The idea (as explained by Jim LoVerde) on an upgrade lock is that only one owner can hold an upgrade lock, but while that is held, it is possible for read locks to exist and/or be obtained, and when the request is made to upgrade to a write lock by the same owner, the lock manager prevents additional read locks until the write lock can be aquired.

In this sense the write lock becomes preferred over all other locks when it gets upgraded from a upgrate lock. Preferred means that if it has to wait and others wait as well it will be served before all other none preferred locking requests.

Calls to acquireRead(Object, long), acquireUpgrade(Object, long) and acquireWrite(Object, long) are blocking and reentrant. Blocking means they will wait if they can not acquire the descired access, reentrant means that a lock request by a specific owner will always be compatible with other accesses on this lock by the same owner. E.g. if you already have a lock for writing and you try to acquire write access again you will not be blocked by this first lock, while others of course will be. This is the natural way you already know from Java monitors and synchronized blocks.

Since:
1.1
Version:
$Revision$
See Also:
GenericLock, ReadWriteLock, ReadWriteUpgradeLockManager

Nested Class Summary
 
Nested classes/interfaces inherited from class org.apache.commons.transaction.locking.GenericLock
GenericLock.LockOwner
 
Field Summary
static int NO_LOCK
           
static int READ_LOCK
           
static int UPGRADE_LOCK
           
static int WRITE_LOCK
           
 
Fields inherited from class org.apache.commons.transaction.locking.GenericLock
logger, owners, resourceId, waiters, waitingOwners
 
Fields inherited from interface org.apache.commons.transaction.locking.MultiLevelLock2
COMPATIBILITY_NONE, COMPATIBILITY_REENTRANT, COMPATIBILITY_REENTRANT_AND_SUPPORT, COMPATIBILITY_SUPPORT
 
Constructor Summary
ReadWriteUpgradeLock(java.lang.Object resourceId, LoggerFacade logger)
          Creates a new read/write/upgrade lock.
 
Method Summary
 boolean acquire(java.lang.Object ownerId, int targetLockLevel, boolean wait, int compatibility, boolean preferred, long timeoutMSecs)
          Tries to acquire a certain lock level on this lock.
 boolean acquireRead(java.lang.Object ownerId, long timeoutMSecs)
          Tries to acquire a blocking, reentrant read lock.
 boolean acquireUpgrade(java.lang.Object ownerId, long timeoutMSecs)
          Tries to acquire a reentrant upgrade lock on a resource.
 boolean acquireWrite(java.lang.Object ownerId, long timeoutMSecs)
          Tries to acquire a blocking, reentrant write lock.
 
Methods inherited from class org.apache.commons.transaction.locking.GenericLock
acquire, acquire, acquire, equals, getConflictingOwners, getConflictingOwners, getConflictingWaiters, getLevelMaxLock, getLevelMinLock, getLockLevel, getMaxLevelOwner, getMaxLevelOwner, getMaxLevelOwner, getMaxLevelOwner, getOwner, getResourceId, has, hashCode, isCompatible, registerWaiter, release, setLockLevel, test, toString, tryLock, tryLock, unregisterWaiter
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NO_LOCK

public static final int NO_LOCK
See Also:
Constant Field Values

READ_LOCK

public static final int READ_LOCK
See Also:
Constant Field Values

UPGRADE_LOCK

public static final int UPGRADE_LOCK
See Also:
Constant Field Values

WRITE_LOCK

public static final int WRITE_LOCK
See Also:
Constant Field Values
Constructor Detail

ReadWriteUpgradeLock

public ReadWriteUpgradeLock(java.lang.Object resourceId,
                            LoggerFacade logger)
Creates a new read/write/upgrade lock.

Parameters:
resourceId - identifier for the resource associated to this lock
logger - generic logger used for all kind of debug logging
Method Detail

acquireRead

public boolean acquireRead(java.lang.Object ownerId,
                           long timeoutMSecs)
                    throws java.lang.InterruptedException
Tries to acquire a blocking, reentrant read lock. A read lock is compatible with other read locks, but not with a write lock.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire a certain lock level on this lock
timeoutMSecs - if blocking is enabled by the wait parameter this specifies the maximum wait time in milliseconds
Returns:
true if the lock actually was acquired
Throws:
java.lang.InterruptedException - when the thread waiting on this method is interrupted

acquireUpgrade

public boolean acquireUpgrade(java.lang.Object ownerId,
                              long timeoutMSecs)
                       throws java.lang.InterruptedException
Tries to acquire a reentrant upgrade lock on a resource.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire a certain lock level on this lock
timeoutMSecs - if blocking is enabled by the wait parameter this specifies the maximum wait time in milliseconds
Returns:
true if the lock actually was acquired
Throws:
java.lang.InterruptedException - when the thread waiting on this method is interrupted

acquireWrite

public boolean acquireWrite(java.lang.Object ownerId,
                            long timeoutMSecs)
                     throws java.lang.InterruptedException
Tries to acquire a blocking, reentrant write lock. A write lock is incompatible with any another read or write lock and is thus exclusive.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire a certain lock level on this lock
timeoutMSecs - if blocking is enabled by the wait parameter this specifies the maximum wait time in milliseconds
Returns:
true if the lock actually was acquired
Throws:
java.lang.InterruptedException - when the thread waiting on this method is interrupted

acquire

public boolean acquire(java.lang.Object ownerId,
                       int targetLockLevel,
                       boolean wait,
                       int compatibility,
                       boolean preferred,
                       long timeoutMSecs)
                throws java.lang.InterruptedException
Description copied from interface: MultiLevelLock2
Tries to acquire a certain lock level on this lock. Does the same as MultiLevelLock.acquire(java.lang.Object, int, boolean, boolean, long) except that it allows for different compatibility settings. There is an additional compatibility mode MultiLevelLock2.COMPATIBILITY_SUPPORTthat allows equal lock levels not to interfere with each other. This is like an additional shared compatibility and useful when you only want to make sure not to interfer with lowe levels, but are fine with the same.

Specified by:
acquire in interface MultiLevelLock2
Overrides:
acquire in class GenericLock
Parameters:
ownerId - a unique id identifying the entity that wants to acquire a certain lock level on this lock
targetLockLevel - the lock level to acquire
wait - true if this method shall block when the desired lock level can not be acquired
compatibility - MultiLevelLock2.COMPATIBILITY_NONEif no additional compatibility is desired (same as reentrant set to false) , MultiLevelLock2.COMPATIBILITY_REENTRANTif lock level by the same owner shall not affect compatibility (same as reentrant set to true), or MultiLevelLock2.COMPATIBILITY_SUPPORTif lock levels that are the same as the desired shall not affect compatibility, or finally MultiLevelLock2.COMPATIBILITY_REENTRANT_AND_SUPPORTwhich is a combination of reentrant and support
preferred - in case this lock request is incompatible with existing ones and we wait, it shall be granted before other waiting requests that are not preferred
timeoutMSecs - if blocking is enabled by the wait parameter this specifies the maximum wait time in milliseconds
Returns:
true if the lock actually was acquired
Throws:
java.lang.InterruptedException - when the thread waiting on this method is interrupted
See Also:
GenericLock.acquire(Object, int, boolean, int, boolean, long)


Copyright ? 2004 The Apache Software Foundation. All Rights Reserved.