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(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 |
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(java.lang.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(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 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:
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 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:
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 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:
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_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
- Throws:
java.lang.InterruptedException
- See Also:
GenericLock.acquire(Object, int, boolean, int, boolean, long)
Copyright © 2004-2007 The Apache Software Foundation. All Rights Reserved.