|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.transaction.locking.GenericLock
A generic implementaion 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(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
maxLockLevel
to 2
.
Now, there are two pairs of levels
NO LOCK
with EXCLUSIVE
SHARED
with SHARED
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 |
3
which might stand for WRITE
access.
Field Summary | |
static int |
COMPATIBILITY_NONE
|
static int |
COMPATIBILITY_REENTRANT
|
static int |
COMPATIBILITY_REENTRANT_AND_SUPPORT
|
static int |
COMPATIBILITY_SUPPORT
|
protected LoggerFacade |
logger
|
Constructor Summary | |
GenericLock(Object resourceId,
int maxLockLevel,
LoggerFacade logger)
Creates a new lock. |
Method Summary | |
boolean |
acquire(Object ownerId,
int targetLockLevel,
boolean wait,
boolean reentrant,
long timeoutMSecs)
Tries to acquire a certain lock level on this lock. |
boolean |
acquire(Object ownerId,
int targetLockLevel,
boolean wait,
int compatibility,
long timeoutMSecs)
Tries to acquire a certain lock level on this lock. |
int |
getLevelMaxLock()
Gets the highst lock level possible. |
int |
getLevelMinLock()
Gets the lowest lock level possible. |
int |
getLockLevel(Object ownerId)
Retuns the highest lock level the specified owner holds on this lock or 0 if it holds no locks at all. |
protected org.apache.commons.transaction.locking.GenericLock.LockOwner |
getMaxLevelOwner()
|
protected org.apache.commons.transaction.locking.GenericLock.LockOwner |
getMaxLevelOwner(org.apache.commons.transaction.locking.GenericLock.LockOwner reentrantOwner)
|
protected org.apache.commons.transaction.locking.GenericLock.LockOwner |
getMaxLevelOwner(org.apache.commons.transaction.locking.GenericLock.LockOwner reentrantOwner,
int supportLockLevel)
|
protected org.apache.commons.transaction.locking.GenericLock.LockOwner |
getMaxLevelOwner(int supportLockLevel)
|
Object |
getOwner()
|
Object |
getResourceId()
Gets the resource assotiated to this lock. |
void |
release(Object ownerId)
Releases any lock levels the specified owner may hold on this lock. |
protected void |
setLockLevel(Object ownerId,
org.apache.commons.transaction.locking.GenericLock.LockOwner lock,
int targetLockLevel)
|
boolean |
test(Object ownerId,
int targetLockLevel,
int compatibility)
Tests if a certain lock level could be acquired. |
String |
toString()
|
protected boolean |
tryLock(Object ownerId,
int targetLockLevel,
int compatibility)
|
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final int COMPATIBILITY_NONE
public static final int COMPATIBILITY_REENTRANT
public static final int COMPATIBILITY_SUPPORT
public static final int COMPATIBILITY_REENTRANT_AND_SUPPORT
protected LoggerFacade logger
Constructor Detail |
public GenericLock(Object resourceId, int maxLockLevel, LoggerFacade logger)
resourceId
- identifier for the resource associated to this lockmaxLockLevel
- highest allowed lock level as described in class intrologger
- generic logger used for all kind of debug loggingMethod Detail |
public boolean test(Object ownerId, int targetLockLevel, int compatibility)
ownerId
- a unique id identifying the entity that wants to acquire a certain lock level on this locktargetLockLevel
- the lock level to acquirecompatibility
- COMPATIBILITY_NONE
if no additional compatibility is
desired (same as reentrant set to false) ,
COMPATIBILITY_REENTRANT
if lock level by the same
owner shall not affect compatibility (same as reentrant set to
true), or COMPATIBILITY_SUPPORT
if lock levels that
are the same as the desired shall not affect compatibility, or finally
COMPATIBILITY_REENTRANT_AND_SUPPORT
which is a combination of reentrant and support
true
if the lock could be acquired acquired at the time this method
was calledpublic boolean acquire(Object ownerId, int targetLockLevel, boolean wait, boolean reentrant, long timeoutMSecs) throws InterruptedException
MultiLevelLock
acquire
in interface MultiLevelLock
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 acquiredreentrant
- true
if lock levels of the same entity acquired earlier
should not restrict compatibility with the lock level desired nowtimeoutMSecs
- if blocking is enabled by the wait
parameter this specifies the maximum wait time in milliseconds
true
if the lock actually was acquired
InterruptedException
- when the thread waiting on this method is interruptedMultiLevelLock.acquire(java.lang.Object,
int, boolean, boolean, long)
public boolean acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility, long timeoutMSecs) throws InterruptedException
MultiLevelLock.acquire(java.lang.Object, int, boolean, boolean, long)
except that it allows for different compatibility settings. There is an
additional compatibility mode 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.
compatibility
- COMPATIBILITY_NONE
if no additional compatibility is
desired (same as reentrant set to false) ,
COMPATIBILITY_REENTRANT
if lock level by the same
owner shall not affect compatibility (same as reentrant set to
true), or COMPATIBILITY_SUPPORT
if lock levels that
are the same as the desired shall not affect compatibility, or finally
COMPATIBILITY_REENTRANT_AND_SUPPORT
which is a combination of reentrant and support
InterruptedException
MultiLevelLock.acquire(java.lang.Object,
int, boolean, boolean, long)
public void release(Object ownerId)
MultiLevelLock
release
in interface MultiLevelLock
ownerId
- a unique id identifying the entity that wants to release all lock levelsMultiLevelLock.release(Object)
public int getLockLevel(Object ownerId)
MultiLevelLock
0
if it holds no locks at all.
getLockLevel
in interface MultiLevelLock
ownerId
- a unique id identifying the entity that wants to know its highest lock level
MultiLevelLock.getLockLevel(Object)
public Object getResourceId()
public int getLevelMinLock()
public int getLevelMaxLock()
public Object getOwner()
public String toString()
protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner()
protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner(org.apache.commons.transaction.locking.GenericLock.LockOwner reentrantOwner)
protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner(int supportLockLevel)
protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner(org.apache.commons.transaction.locking.GenericLock.LockOwner reentrantOwner, int supportLockLevel)
protected void setLockLevel(Object ownerId, org.apache.commons.transaction.locking.GenericLock.LockOwner lock, int targetLockLevel)
protected boolean tryLock(Object ownerId, int targetLockLevel, int compatibility)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |