| java.lang.Object
 org.apache.commons.transaction.locking.GenericLock
All known Subclasses: org.apache.commons.transaction.locking.ReadWriteLock, org.apache.commons.transaction.locking.ReadWriteUpgradeLock,
| GenericLock | | public class GenericLock implements MultiLevelLock2(Code) | | A generic implementain of a simple multi level lock.
The idea is to have an ascending number of lock levels ranging from
0 to maxLockLevel as specified in
GenericLock.GenericLock(Object,int,LoggerFacade) : the higher the lock level
the stronger and more restrictive the lock. To determine which lock may
coexist with other locks you have to imagine matching pairs of lock levels.
For each pair both parts allow for all lock levels less than or equal to the
matching other part. Pairs are composed by the lowest and highest level not
yet part of a pair and successively applying this method until no lock level
is left. For an even amount of levels each level is part of exactly one pair.
For an odd amount the middle level is paired with itself. The highst lock
level may coexist with the lowest one (0) which by
definition means NO LOCK. This implies that you will have to
specify at least one other lock level and thus set maxLockLevel
to at least 1.
Although this may sound complicated, in practice this is quite simple. Let us
imagine you have three lock levels:
0:NO LOCK (always needed by the
implementation of this lock)
1:SHARED
2:EXCLUSIVE
Accordingly, you will have to set maxLockLevel to
2. Now, there are two pairs of levels
NO LOCK with EXCLUSIVE
SHARED with SHARED
This means when the current highest lock level is NO LOCK
everything less or equal to EXCLUSIVE is allowed - which means
every other lock level. On the other side EXCLUSIVE allows
exacly for NO LOCK- which means nothing else. In conclusion,
SHARED allows for SHARED or NO
LOCK,
but not for EXCLUSIVE. To make this very clear have a look at
this table, where o means compatible or can coexist and
x means incompatible or can not coexist:
|
NO LOCK |
SHARED |
EXCLUSIVE |
| NO LOCK |
o |
o |
o |
| SHARED |
o |
o |
x |
| EXCLUSIVE |
o |
x |
x |
Additionally, there are preferences for specific locks you can pass to
GenericLock.acquire(Object,int,boolean,int,boolean,long) .
This means whenever more thanone party
waits for a lock you can specify which one is to be preferred. This gives you
every freedom you might need to specifcy e.g.
- priority to parties either applying for higher or lower lock levels
- priority not only to higher or lower locks, but to a specific level
- completely random preferences
version:
$Id: GenericLock.java 493628 2007-01-07 01:42:48Z joerg $ |
| Inner Class :protected static class LockOwner | |
| Method Summary | |
| public synchronized boolean | acquire(Object ownerId, int targetLockLevel, boolean wait, boolean reentrant, long timeoutMSecs)
| | public synchronized boolean | acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility, long timeoutMSecs)
| | public synchronized boolean | acquire(Object ownerId, int targetLockLevel, boolean preferred, long timeoutMSecs)
Tries to blockingly acquire a lock which can be preferred. | | public synchronized boolean | acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility, boolean preferred, long timeoutMSecs)
| | public boolean | equals(Object o)
| | protected Set | getConflictingOwners(Object ownerId, int targetLockLevel, int compatibility)
| | protected Set | getConflictingOwners(LockOwner myOwner, Collection ownersToTest)
| | protected Collection | getConflictingWaiters(Object ownerId)
| | public int | getLevelMaxLock()
Gets the highst lock level possible. | | public int | getLevelMinLock()
Gets the lowest lock level possible. | | public int | getLockLevel(Object ownerId)
| | protected synchronized LockOwner | getMaxLevelOwner()
| | protected synchronized LockOwner | getMaxLevelOwner(LockOwner reentrantOwner, boolean preferred)
| | protected synchronized LockOwner | getMaxLevelOwner(int supportLockLevel, boolean preferred)
| | protected synchronized LockOwner | getMaxLevelOwner(LockOwner reentrantOwner, int supportLockLevel, boolean preferred)
| | public Object | getOwner()
| | public Object | getResourceId()
Gets the resource assotiated to this lock. | | public boolean | has(Object ownerId, int lockLevel)
| | public int | hashCode()
| | protected boolean | isCompatible(int targetLockLevel, int currentLockLevel)
| | protected void | registerWaiter(LockOwner waitingOwner)
| | public synchronized boolean | release(Object ownerId)
| | protected synchronized void | setLockLevel(Object ownerId, LockOwner lock, int targetLockLevel, int compatibility, boolean intention)
| | public boolean | test(Object ownerId, int targetLockLevel, int compatibility)
| | public synchronized String | toString()
| | protected boolean | tryLock(Object ownerId, int targetLockLevel, int compatibility, boolean preferred)
| | protected synchronized boolean | tryLock(Object ownerId, int targetLockLevel, int compatibility, boolean preferred, boolean tryOnly)
| | protected void | unregisterWaiter(LockOwner waitingOwner)
|
| waiters | | protected int waiters(Code) | | |
| GenericLock | | public GenericLock(Object resourceId, int maxLockLevel, LoggerFacade logger)(Code) | | Creates a new lock.
Parameters:
resourceId - identifier for the resource associated to this lock
Parameters:
maxLockLevel - highest allowed lock level as described in class intro
Parameters:
logger - generic logger used for all kind of debug logging |
| getConflictingOwners | | protected Set getConflictingOwners(Object ownerId, int targetLockLevel, int compatibility)(Code) | | |
| getConflictingOwners | | protected Set getConflictingOwners(LockOwner myOwner, Collection ownersToTest)(Code) | | |
| getLevelMaxLock | | public int getLevelMaxLock()(Code) | | Gets the highst lock level possible.
maximum lock level |
| getLevelMinLock | | public int getLevelMinLock()(Code) | | Gets the lowest lock level possible.
minimum lock level |
| getMaxLevelOwner | | protected synchronized LockOwner getMaxLevelOwner()(Code) | | |
| getMaxLevelOwner | | protected synchronized LockOwner getMaxLevelOwner(LockOwner reentrantOwner, boolean preferred)(Code) | | |
| getMaxLevelOwner | | protected synchronized LockOwner getMaxLevelOwner(int supportLockLevel, boolean preferred)(Code) | | |
| getMaxLevelOwner | | protected synchronized LockOwner getMaxLevelOwner(LockOwner reentrantOwner, int supportLockLevel, boolean preferred)(Code) | | |
| getResourceId | | public Object getResourceId()(Code) | | Gets the resource assotiated to this lock.
identifier for the resource associated to this lock |
| hashCode | | public int hashCode()(Code) | | |
| isCompatible | | protected boolean isCompatible(int targetLockLevel, int currentLockLevel)(Code) | | |
| registerWaiter | | protected void registerWaiter(LockOwner waitingOwner)(Code) | | |
| setLockLevel | | protected synchronized void setLockLevel(Object ownerId, LockOwner lock, int targetLockLevel, int compatibility, boolean intention)(Code) | | |
| tryLock | | protected boolean tryLock(Object ownerId, int targetLockLevel, int compatibility, boolean preferred)(Code) | | |
| tryLock | | protected synchronized boolean tryLock(Object ownerId, int targetLockLevel, int compatibility, boolean preferred, boolean tryOnly)(Code) | | |
| unregisterWaiter | | protected void unregisterWaiter(LockOwner waitingOwner)(Code) | | |
|
|