org.apache.commons.transaction.locking
Interface LockManager2

All Known Implementing Classes:
GenericLockManager, ReadWriteLockManager, ReadWriteUpgradeLockManager

public interface LockManager2

Extended version of a lock manager that also has global knowledge or all locks and should be used as a delegate for all locking requests. This allows for things like deadlock detection.

Since:
1.1
Version:
$Id: LockManager2.java 493628 2007-01-07 01:42:48Z joerg $
See Also:
MultiLevelLock, MultiLevelLock2, LockManager, GenericLockManager, GenericLock

Method Summary
 boolean checkLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)
          Determines if a lock could be acquire without actually acquiring it.
 Set getAll(Object ownerId)
          Gets all locks (partially) held by an owner.
 int getLevel(Object ownerId, Object resourceId)
          Gets the lock level held by certain owner on a certain resource.
 MultiLevelLock getLock(Object resourceId)
          Gets an existing lock on the specified resource.
 boolean hasLock(Object ownerId, Object resourceId, int lockLevel)
          Determines if a lock is owner by an owner.
 void lock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)
          Tries to acquire a lock on a resource.
 void lock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant, long timeoutMSecs)
          Tries to acquire a lock on a resource.
 void lock(Object ownerId, Object resourceId, int targetLockLevel, int compatibility, boolean preferred, long timeoutMSecs)
          Most flexible way to acquire a lock on a resource.
 boolean release(Object ownerId, Object resourceId)
          Releases all locks for a certain resource held by a certain owner.
 void releaseAll(Object ownerId)
          Releases all locks (partially) held by an owner.
 void removeLock(MultiLevelLock lock)
          Removes the specified lock from the associated resource.
 void startGlobalTimeout(Object ownerId, long timeoutMSecs)
          Starts a global timeout for an owner.
 boolean tryLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)
          Tries to acquire a lock on a resource.
 

Method Detail

hasLock

boolean hasLock(Object ownerId,
                Object resourceId,
                int lockLevel)
Determines if a lock is owner by an owner.

Parameters:
ownerId - a unique id identifying the entity that wants to check this lock
resourceId - the resource to get the level for
lockLevel - the lock level to check
Returns:
true if the owner has the lock, false otherwise

checkLock

boolean checkLock(Object ownerId,
                  Object resourceId,
                  int targetLockLevel,
                  boolean reentrant)
Determines if a lock could be acquire without actually acquiring it.

This method does not block, but immediatly returns.

Parameters:
ownerId - a unique id identifying the entity that wants to check this lock
resourceId - the resource to get the level for
targetLockLevel - the lock level to check
reentrant - true if this request shall not be influenced by other locks held by the same owner
Returns:
true if the lock could be acquired, false otherwise

tryLock

boolean tryLock(Object ownerId,
                Object resourceId,
                int targetLockLevel,
                boolean reentrant)
Tries to acquire a lock on a resource.

This method does not block, but immediatly returns. If a lock is not available false will be returned.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire this lock
resourceId - the resource to get the level for
targetLockLevel - the lock level to acquire
reentrant - true if this request shall not be influenced by other locks held by the same owner
Returns:
true if the lock has been acquired, false otherwise

lock

void lock(Object ownerId,
          Object resourceId,
          int targetLockLevel,
          boolean reentrant)
          throws LockException
Tries to acquire a lock on a resource.

This method blocks and waits for the lock in case it is not avaiable. If there is a timeout or a deadlock or the thread is interrupted a LockException is thrown.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire this lock
resourceId - the resource to get the level for
targetLockLevel - the lock level to acquire
reentrant - true if this request shall not be blocked by other locks held by the same owner
Throws:
LockException - will be thrown when the lock can not be acquired

lock

void lock(Object ownerId,
          Object resourceId,
          int targetLockLevel,
          boolean reentrant,
          long timeoutMSecs)
          throws LockException
Tries to acquire a lock on a resource.

This method blocks and waits for the lock in case it is not avaiable. If there is a timeout or a deadlock or the thread is interrupted a LockException is thrown.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire this lock
resourceId - the resource to get the level for
targetLockLevel - the lock level to acquire
reentrant - true if this request shall not be blocked by other locks held by the same owner
timeoutMSecs - specifies the maximum wait time in milliseconds
Throws:
LockException - will be thrown when the lock can not be acquired

lock

void lock(Object ownerId,
          Object resourceId,
          int targetLockLevel,
          int compatibility,
          boolean preferred,
          long timeoutMSecs)
          throws LockException
Most flexible way to acquire a lock on a resource.

This method blocks and waits for the lock in case it is not avaiable. If there is a timeout or a deadlock or the thread is interrupted a LockException is thrown.

Parameters:
ownerId - a unique id identifying the entity that wants to acquire this lock
resourceId - the resource to get the level for
targetLockLevel - the lock level to acquire
compatibility - MultiLevelLock2.COMPATIBILITY_NONEif no additional compatibility is desired (same as reentrant set to false) , MultiLevelLock2.COMPATIBILITY_REENTRANTif lock level by the same owner shall not affect compatibility (same as reentrant set to true), or MultiLevelLock2.COMPATIBILITY_SUPPORTif lock levels that are the same as the desired shall not affect compatibility, or finally MultiLevelLock2.COMPATIBILITY_REENTRANT_AND_SUPPORTwhich is a combination of reentrant and support
preferred - in case this lock request is incompatible with existing ones and we wait, it shall be granted before other waiting requests that are not preferred
timeoutMSecs - specifies the maximum wait time in milliseconds
Throws:
LockException - will be thrown when the lock can not be acquired

startGlobalTimeout

void startGlobalTimeout(Object ownerId,
                        long timeoutMSecs)
Starts a global timeout for an owner. This is especially usefull, when the owner is a transaction. After a global timeout occurs all of the owner's lock will be released and the owner will not be allowed to access any locks before before calling releaseAll(Object).

Parameters:
ownerId - a unique id identifying the entity that wants to acquire this lock
timeoutMSecs - specifies the global timeout in milliseconds

getLevel

int getLevel(Object ownerId,
             Object resourceId)
Gets the lock level held by certain owner on a certain resource.

Parameters:
ownerId - the id of the owner of the lock
resourceId - the resource to get the level for

release

boolean release(Object ownerId,
                Object resourceId)
Releases all locks for a certain resource held by a certain owner.

Parameters:
ownerId - the id of the owner of the lock
resourceId - the resource to releases the lock for
Returns:
true if the lock actually was released, false in case there was no lock held by the owner

releaseAll

void releaseAll(Object ownerId)
Releases all locks (partially) held by an owner.

Parameters:
ownerId - the id of the owner

getAll

Set getAll(Object ownerId)
Gets all locks (partially) held by an owner.

Parameters:
ownerId - the id of the owner
Returns:
all locks held by ownerId

getLock

MultiLevelLock getLock(Object resourceId)
Gets an existing lock on the specified resource. If none exists it returns null.

Parameters:
resourceId - the resource to get the lock for
Returns:
the lock on the specified resource

removeLock

void removeLock(MultiLevelLock lock)
Removes the specified lock from the associated resource. Caution: This does not release the lock, but only moves it out of the scope of this manager. Use release(Object, Object) for that.

Parameters:
lock - the lock to be removed


Copyright © 2004-2009 Apache Software Foundation. All Rights Reserved.