org.apache.commons.transaction.locking
Class GenericLock

java.lang.Object
  extended byorg.apache.commons.transaction.locking.GenericLock
All Implemented Interfaces:
MultiLevelLock
Direct Known Subclasses:
ReadWriteLock

public class GenericLock
extends Object
implements MultiLevelLock

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:

Accordingly, you will have to set maxLockLevel to 2. Now, there are two pairs of levels 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 SHAREDEXCLUSIVE
NO LOCKooo
SHAREDoox
EXCLUSIVEoxx

General limitations include:

Version:
$Revision: 1.2 $

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

COMPATIBILITY_NONE

public static final int COMPATIBILITY_NONE
See Also:
Constant Field Values

COMPATIBILITY_REENTRANT

public static final int COMPATIBILITY_REENTRANT
See Also:
Constant Field Values

COMPATIBILITY_SUPPORT

public static final int COMPATIBILITY_SUPPORT
See Also:
Constant Field Values

COMPATIBILITY_REENTRANT_AND_SUPPORT

public static final int COMPATIBILITY_REENTRANT_AND_SUPPORT
See Also:
Constant Field Values

logger

protected LoggerFacade logger
Constructor Detail

GenericLock

public GenericLock(Object resourceId,
                   int maxLockLevel,
                   LoggerFacade logger)
Creates a new lock.

Parameters:
resourceId - identifier for the resource associated to this lock
maxLockLevel - highest allowed lock level as described in class intro
logger - generic logger used for all kind of debug logging
Method Detail

test

public boolean test(Object ownerId,
                    int targetLockLevel,
                    int compatibility)
Tests if a certain lock level could be acquired.

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
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
Returns:
true if the lock could be acquired acquired at the time this method was called

acquire

public boolean acquire(Object ownerId,
                       int targetLockLevel,
                       boolean wait,
                       boolean reentrant,
                       long timeoutMSecs)
                throws InterruptedException
Description copied from interface: MultiLevelLock
Tries to acquire a certain lock level on this lock.

Specified by:
acquire in interface MultiLevelLock
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
reentrant - true if lock levels of the same entity acquired earlier should not restrict compatibility with the lock level desired now
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:
InterruptedException - when the thread waiting on this method is interrupted
See Also:
MultiLevelLock.acquire(java.lang.Object, int, boolean, boolean, long)

acquire

public boolean acquire(Object ownerId,
                       int targetLockLevel,
                       boolean wait,
                       int compatibility,
                       long timeoutMSecs)
                throws InterruptedException
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 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.

Parameters:
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
Throws:
InterruptedException
See Also:
MultiLevelLock.acquire(java.lang.Object, int, boolean, boolean, long)

release

public void release(Object ownerId)
Description copied from interface: MultiLevelLock
Releases any lock levels the specified owner may hold on this lock.

Specified by:
release in interface MultiLevelLock
Parameters:
ownerId - a unique id identifying the entity that wants to release all lock levels
See Also:
MultiLevelLock.release(Object)

getLockLevel

public int getLockLevel(Object ownerId)
Description copied from interface: MultiLevelLock
Retuns the highest lock level the specified owner holds on this lock or 0 if it holds no locks at all.

Specified by:
getLockLevel in interface MultiLevelLock
Parameters:
ownerId - a unique id identifying the entity that wants to know its highest lock level
Returns:
the highest lock level
See Also:
MultiLevelLock.getLockLevel(Object)

getResourceId

public Object getResourceId()
Gets the resource assotiated to this lock.

Returns:
identifier for the resource associated to this lock

getLevelMinLock

public int getLevelMinLock()
Gets the lowest lock level possible.

Returns:
minimum lock level

getLevelMaxLock

public int getLevelMaxLock()
Gets the highst lock level possible.

Returns:
maximum lock level

getOwner

public Object getOwner()

toString

public String toString()

getMaxLevelOwner

protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner()

getMaxLevelOwner

protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner(org.apache.commons.transaction.locking.GenericLock.LockOwner reentrantOwner)

getMaxLevelOwner

protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner(int supportLockLevel)

getMaxLevelOwner

protected org.apache.commons.transaction.locking.GenericLock.LockOwner getMaxLevelOwner(org.apache.commons.transaction.locking.GenericLock.LockOwner reentrantOwner,
                                                                                        int supportLockLevel)

setLockLevel

protected void setLockLevel(Object ownerId,
                            org.apache.commons.transaction.locking.GenericLock.LockOwner lock,
                            int targetLockLevel)

tryLock

protected boolean tryLock(Object ownerId,
                          int targetLockLevel,
                          int compatibility)


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