org.apache.commons.transaction.locking
Class ReadWriteUpgradeLock
java.lang.Object
org.apache.commons.transaction.locking.GenericLock
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
Method Summary |
boolean |
acquire(Object ownerId,
int targetLockLevel,
boolean wait,
int compatibility,
boolean preferred,
long timeoutMSecs)
Tries to acquire a certain lock level on this lock. |
boolean |
acquireRead(Object ownerId,
long timeoutMSecs)
Tries to acquire a blocking, reentrant read lock. |
boolean |
acquireUpgrade(Object ownerId,
long timeoutMSecs)
Tries to acquire a reentrant upgrade lock on a resource. |
boolean |
acquireWrite(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 |
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
ReadWriteUpgradeLock
public ReadWriteUpgradeLock(Object resourceId,
LoggerFacade logger)
- Creates a new read/write/upgrade lock.
- Parameters:
resourceId
- identifier for the resource associated to this locklogger
- generic logger used for all kind of debug logging
acquireRead
public boolean acquireRead(Object ownerId,
long timeoutMSecs)
throws 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 locktimeoutMSecs
- 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:
InterruptedException
- when the thread waiting on this method is interrupted
acquireUpgrade
public boolean acquireUpgrade(Object ownerId,
long timeoutMSecs)
throws 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 locktimeoutMSecs
- 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:
InterruptedException
- when the thread waiting on this method is interrupted
acquireWrite
public boolean acquireWrite(Object ownerId,
long timeoutMSecs)
throws 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 locktimeoutMSecs
- 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:
InterruptedException
- when the thread waiting on this method is interrupted
acquire
public boolean acquire(Object ownerId,
int targetLockLevel,
boolean wait,
int compatibility,
boolean preferred,
long timeoutMSecs)
throws 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_SUPPORT
that 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 locktargetLockLevel
- the lock level to acquirewait
- true
if this method shall block when the desired lock level can not be acquiredcompatibility
- MultiLevelLock2.COMPATIBILITY_NONE
if no additional compatibility is
desired (same as reentrant set to false) ,
MultiLevelLock2.COMPATIBILITY_REENTRANT
if lock level by the same
owner shall not affect compatibility (same as reentrant set to
true), or MultiLevelLock2.COMPATIBILITY_SUPPORT
if lock levels that
are the same as the desired shall not affect compatibility, or
finally MultiLevelLock2.COMPATIBILITY_REENTRANT_AND_SUPPORT
which is
a combination of reentrant and supportpreferred
- in case this lock request is incompatible with existing ones
and we wait, it shall be granted before other waiting requests
that are not preferredtimeoutMSecs
- 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:
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.