Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.transaction.locking
Class GenericLockManager

    java.lang.Object
      org.apache.commons.transaction.locking.GenericLockManager

All Implemented Interfaces:
  LockManager, LockManager2

Direct Known Subclasses:
  ReadWriteLockManager

public class GenericLockManager
extends Object
implements LockManager, LockManager2

Manager for `GenericLock`s on resources. This implementation includes

- deadlock detection, which is configurable to come into effect after an initial short waiting lock request; this is useful as it is somewhat expensive
- global transaction timeouts that actively revoke granted rights from transactions

Version:
  $Revision$

Field Summary
`protected long` | `checkThreshhold`
`static long` | `DEFAULT_CHECK_THRESHHOLD`
`static long` | `DEFAULT_TIMEOUT`
`protected Map` | `effectiveGlobalTimeouts` Maps onwerId to global effective time outs (i.e. the time the lock will time out).
`protected Map` | `globalLocks` Maps resourceId to lock.
`protected Map` | `globalOwners` Maps onwerId to locks it (partially) owns.
`protected long` | `globalTimeoutMSecs`
`protected LoggerFacade` | `logger`
`protected int` | `maxLockLevel`
`protected Set` | `timedOutOwners`

Constructor Summary
`GenericLockManager(int maxLockLevel, LoggerFacade logger)`
`GenericLockManager(int maxLockLevel, LoggerFacade logger, long timeoutMSecs)`
`GenericLockManager(int maxLockLevel, LoggerFacade logger, long timeoutMSecs, long checkThreshholdMSecs)` Creates a new generic lock manager.

Method Summary
`protected void` | `addOwner(Object ownerId, GenericLock lock)`
`MultiLevelLock` | `atomicGetOrCreateLock(Object resourceId)` Either gets an existing lock on the specified resource or creates one if none exists.
`boolean` | `checkLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)` Determines if a lock could be acquire without actually acquiring it.
`protected GenericLock` | `createLock(Object resourceId)`
`protected void` | `doLock(GenericLock lock, Object ownerId, Object resourceId, int targetLockLevel, int compatibility, boolean preferred, long timeoutMSecs)`
`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.
`Collection` | `getLocks()` Gets all locks as orignials, no copies.
`protected long` | `getNextGlobalConflictTimeout(Set conflicts)`
`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.
`protected void` | `releaseAllNoTimeOutReset(Object ownerId)`
`protected boolean` | `releaseTimedOutOwners()`
`void` | `removeLock(MultiLevelLock lock)` Removes the specified lock from the associated resource.
`protected void` | `removeOwner(Object ownerId, GenericLock lock)`
`void` | `startGlobalTimeout(Object ownerId, long timeoutMSecs)` Starts a global timeout for an owner.
`protected boolean` | `timeOut(Object ownerId)`
`protected void` | `timeoutCheck(Object ownerId)`
`String` | `toString()`
`boolean` | `tryLock(Object ownerId, Object resourceId, int targetLockLevel, boolean reentrant)` Tries to acquire a lock on a resource.
`protected boolean` | `wouldDeadlock(Object ownerId, Set path)` Checks if an owner is deadlocked.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### DEFAULT_TIMEOUT

    public static final long DEFAULT_TIMEOUT

See Also:
  Constant Field Values

### DEFAULT_CHECK_THRESHHOLD

    public static final long DEFAULT_CHECK_THRESHHOLD

See Also:
  Constant Field Values

### globalOwners

    protected Map globalOwners

  Maps onwerId to locks it (partially) owns.

### globalLocks

    protected Map globalLocks

  Maps resourceId to lock.

### effectiveGlobalTimeouts

    protected Map effectiveGlobalTimeouts

  Maps onwerId to global effective time outs (i.e. the time the lock will time out).

### timedOutOwners

    protected Set timedOutOwners

### maxLockLevel

    protected int maxLockLevel

### logger

    protected LoggerFacade logger

### globalTimeoutMSecs

    protected long globalTimeoutMSecs

### checkThreshhold

    protected long checkThreshhold

Constructor Detail

### GenericLockManager

    public GenericLockManager(int maxLockLevel,
                              LoggerFacade logger,
                              long timeoutMSecs,
                              long checkThreshholdMSecs)
                       throws IllegalArgumentException

  Creates a new generic lock manager.

Parameters:
  `maxLockLevel` - highest allowed lock level as described in `GenericLock` 's class intro
  `logger` - generic logger used for all kind of debug logging
  `timeoutMSecs` - specifies the maximum time to wait for a lock in milliseconds
  `checkThreshholdMSecs` - specifies a special wait threshhold before deadlock and timeout detection come into play or `-1` switch it off and check for directly
Throws:
  `IllegalArgumentException` - if maxLockLevel is less than 1
Since:
  1.1

### GenericLockManager

    public GenericLockManager(int maxLockLevel,
                              LoggerFacade logger,
                              long timeoutMSecs)
                       throws IllegalArgumentException

### GenericLockManager

    public GenericLockManager(int maxLockLevel,
                              LoggerFacade logger)
                       throws IllegalArgumentException

Method Detail

### startGlobalTimeout

    public void startGlobalTimeout(Object ownerId,
                                   long timeoutMSecs)

  Description copied from interface: `LockManager2`
  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 `LockManager2.releaseAll(Object)`.

  Specified by:
    `startGlobalTimeout` in interface `LockManager2`
  Parameters:
    `ownerId` - a unique id identifying the entity that wants to acquire this lock
    `timeoutMSecs` - specifies the global timeout in milliseconds
  Since:
    1.1
  See Also:
    `LockManager2.startGlobalTimeout(Object, long)`

### tryLock

    public boolean tryLock(Object ownerId,
                           Object resourceId,
                           int targetLockLevel,
                           boolean reentrant)

  Description copied from interface: `LockManager2`
  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.

  Specified by:
    `tryLock` in interface `LockManager2`
  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
  Since:
    1.1
  See Also:
    `LockManager2.tryLock(Object, Object, int, boolean)`

### checkLock

    public boolean checkLock(Object ownerId,
                             Object resourceId,
                             int targetLockLevel,
                             boolean reentrant)

  Description copied from interface: `LockManager2`
  Determines if a lock could be acquire without actually acquiring it.
  This method does not block, but immediatly returns.

  Specified by:
    `checkLock` in interface `LockManager2`
  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
  Since:
    1.1
  See Also:
    `LockManager2.checkLock(Object, Object, int, boolean)`

### hasLock

    public boolean hasLock(Object ownerId,
                           Object resourceId,
                           int lockLevel)

  Description copied from interface: `LockManager2`
  Determines if a lock is owner by an owner.

  Specified by:
    `hasLock` in interface `LockManager2`
  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
  Since:
    1.1
  See Also:
    `LockManager2.hasLock(Object, Object, int)`

### lock

    public void lock(Object ownerId,
                     Object resourceId,
                     int targetLockLevel,
                     boolean reentrant)
              throws LockException

  Description copied from interface: `LockManager2`
  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.

  Specified by:
    `lock` in interface `LockManager2`
  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
  Since:
    1.1
  See Also:
    `LockManager2.lock(Object, Object, int, boolean)`

### lock

    public void lock(Object ownerId,
                     Object resourceId,
                     int targetLockLevel,
                     boolean reentrant,
                     long timeoutMSecs)
              throws LockException

  Description copied from interface: `LockManager2`
  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.

  Specified by:
    `lock` in interface `LockManager2`
  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
  Since:
    1.1
  See Also:
    `LockManager2.lock(Object, Object, int, boolean, long)`

### lock

    public void lock(Object ownerId,
                     Object resourceId,
                     int targetLockLevel,
                     int compatibility,
                     boolean preferred,
                     long timeoutMSecs)
              throws LockException

  Description copied from interface: `LockManager2`
  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.

  Specified by:
    `lock` in interface `LockManager2`
  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_NONE`if no additional compatibility is desired (same as reentrant set to false) , `MultiLevelLock2.COMPATIBILITY_REENTRANT`if lock level by the same owner shall not affect compatibility (same as reentrant set to true), or `MultiLevelLock2.COMPATIBILITY_SUPPORT`if lock levels that are the same as the desired shall not affect compatibility, or finally `MultiLevelLock2.COMPATIBILITY_REENTRANT_AND_SUPPORT`which 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
  Since:
    1.1
  See Also:
    `LockManager2.lock(Object, Object, int, int, boolean, long)`

### doLock

    protected void doLock(GenericLock lock,
                          Object ownerId,
                          Object resourceId,
                          int targetLockLevel,
                          int compatibility,
                          boolean preferred,
                          long timeoutMSecs)

### getLevel

    public int getLevel(Object ownerId,
                        Object resourceId)

  Description copied from interface: `LockManager2`
  Gets the lock level held by certain owner on a certain resource.

  Specified by:
    `getLevel` in interface `LockManager2`
  Parameters:
    `ownerId` - the id of the owner of the lock
    `resourceId` - the resource to get the level for
  Since:
    1.1
  See Also:
    `LockManager2.getLevel(Object, Object)`

### release

    public boolean release(Object ownerId,
                           Object resourceId)

  Description copied from interface: `LockManager2`
  Releases all locks for a certain resource held by a certain owner.

  Specified by:
    `release` in interface `LockManager2`
  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
  Since:
    1.1
  See Also:
    `LockManager2.release(Object, Object)`

### releaseAll

    public void releaseAll(Object ownerId)

  Description copied from interface: `LockManager2`
  Releases all locks (partially) held by an owner.

  Specified by:
    `releaseAll` in interface `LockManager2`
  Parameters:
    `ownerId` - the id of the owner
  Since:
    1.1
  See Also:
    `LockManager2.releaseAll(Object)`

### releaseAllNoTimeOutReset

    protected void releaseAllNoTimeOutReset(Object ownerId)

### getAll

    public Set getAll(Object ownerId)

  Description copied from interface: `LockManager2`
  Gets all locks (partially) held by an owner.

  Specified by:
    `getAll` in interface `LockManager2`
  Parameters:
    `ownerId` - the id of the owner
  Returns:
    all locks held by ownerId
  Since:
    1.1
  See Also:
    `LockManager2.getAll(Object)`

### addOwner

    protected void addOwner(Object ownerId,
                            GenericLock lock)

### removeOwner

    protected void removeOwner(Object ownerId,
                               GenericLock lock)

### wouldDeadlock

    protected boolean wouldDeadlock(Object ownerId,
                                    Set path)

  Checks if an owner is deadlocked.
  We traverse the tree recursively formed by owners, locks held by them and then again owners waiting for the locks. If there is a cycle in one of the paths from the root to a leaf we have a deadlock.
  A more detailed discussion on deadlocks and definitions and how to detect them can be found in this nice article .
  Caution: This computation can be very expensive with many owners and locks. Worst (unlikely) case is exponential.

  Parameters:
    `ownerId` - the owner to check for being deadlocked
    `path` - initially should be called with an empty set
  Returns:
    `true` if the owner is deadlocked, `false` otherwise

### releaseTimedOutOwners

    protected boolean releaseTimedOutOwners()

### timeOut

    protected boolean timeOut(Object ownerId)

### getNextGlobalConflictTimeout

    protected long getNextGlobalConflictTimeout(Set conflicts)

### getLock

    public MultiLevelLock getLock(Object resourceId)

  Description copied from interface: `LockManager`
  Gets an existing lock on the specified resource. If none exists it returns `null`.

  Specified by:
    `getLock` in interface `LockManager`
  Parameters:
    `resourceId` - the resource to get the lock for
  Returns:
    the lock on the specified resource

### atomicGetOrCreateLock

    public MultiLevelLock atomicGetOrCreateLock(Object resourceId)

  Description copied from interface: `LockManager`
  Either gets an existing lock on the specified resource or creates one if none exists. This methods guarantees to do this atomically.

  Specified by:
    `atomicGetOrCreateLock` in interface `LockManager`
  Parameters:
    `resourceId` - the resource to get or create the lock on
  Returns:
    the lock for the specified resource

### removeLock

    public void removeLock(MultiLevelLock lock)

  Description copied from interface: `LockManager`
  Removes the specified lock from the associated resource.

  Specified by:
    `removeLock` in interface `LockManager`
  Parameters:
    `lock` - the lock to be removed

### getLocks

    public Collection getLocks()

  Gets all locks as orignials, no copies.

  Returns:
    collection holding all locks.

### toString

    public String toString()

### createLock

    protected GenericLock createLock(Object resourceId)

### timeoutCheck

    protected void timeoutCheck(Object ownerId)
                         throws LockException

  Throws:
    `LockException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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