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 GenericLock

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

All Implemented Interfaces:
  MultiLevelLock, MultiLevelLock2

Direct Known Subclasses:
  ReadWriteLock, ReadWriteUpgradeLock

public class GenericLock
extends Object
implements MultiLevelLock2

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`

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 `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:
  $Revision$

Nested Class Summary
`protected static class` | `GenericLock.LockOwner`

Field Summary
`protected LoggerFacade` | `logger`
`protected Map` | `owners`
`protected Object` | `resourceId`
`protected int` | `waiters`
`protected List` | `waitingOwners`

Fields inherited from interface org.apache.commons.transaction.locking.MultiLevelLock2
`COMPATIBILITY_NONE, COMPATIBILITY_REENTRANT, COMPATIBILITY_REENTRANT_AND_SUPPORT, COMPATIBILITY_SUPPORT`

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, boolean preferred, long timeoutMSecs)` Tries to acquire a certain lock level on this lock.
`boolean` | `acquire(Object ownerId, int targetLockLevel, boolean wait, int compatibility, long timeoutMSecs)`
`boolean` | `acquire(Object ownerId, int targetLockLevel, boolean preferred, long timeoutMSecs)` Tries to blockingly acquire a lock which can be preferred.
`boolean` | `equals(Object o)`
`protected Set` | `getConflictingOwners(GenericLock.LockOwner myOwner, Collection ownersToTest)`
`protected Set` | `getConflictingOwners(Object ownerId, int targetLockLevel, int compatibility)`
`protected Collection` | `getConflictingWaiters(Object ownerId)`
`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 GenericLock.LockOwner` | `getMaxLevelOwner()`
`protected GenericLock.LockOwner` | `getMaxLevelOwner(GenericLock.LockOwner reentrantOwner, boolean preferred)`
`protected GenericLock.LockOwner` | `getMaxLevelOwner(GenericLock.LockOwner reentrantOwner, int supportLockLevel, boolean preferred)`
`protected GenericLock.LockOwner` | `getMaxLevelOwner(int supportLockLevel, boolean preferred)`
`Object` | `getOwner()`
`Object` | `getResourceId()` Gets the resource assotiated to this lock.
`boolean` | `has(Object ownerId, int lockLevel)` Tests if a certain lock level is owned by an owner.
`int` | `hashCode()`
`protected boolean` | `isCompatible(int targetLockLevel, int currentLockLevel)`
`protected void` | `registerWaiter(GenericLock.LockOwner waitingOwner)`
`boolean` | `release(Object ownerId)` Releases any lock levels the specified owner may hold on this lock.
`protected void` | `setLockLevel(Object ownerId, GenericLock.LockOwner lock, int targetLockLevel, int compatibility, boolean intention)`
`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, boolean preferred)`
`protected boolean` | `tryLock(Object ownerId, int targetLockLevel, int compatibility, boolean preferred, boolean tryOnly)`
`protected void` | `unregisterWaiter(GenericLock.LockOwner waitingOwner)`

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

Field Detail

### resourceId

    protected Object resourceId

### owners

    protected Map owners

### waitingOwners

    protected List waitingOwners

### logger

    protected LoggerFacade logger

### waiters

    protected int waiters

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

### equals

    public boolean equals(Object o)

### hashCode

    public int hashCode()

### test

    public boolean test(Object ownerId,
                        int targetLockLevel,
                        int compatibility)

  Description copied from interface: `MultiLevelLock2`
  Tests if a certain lock level could be acquired. This method tests only and does not actually acquire the lock.

  Specified by:
    `test` in interface `MultiLevelLock2`
  Parameters:
    `ownerId` - a unique id identifying the entity that wants to test a certain lock level on this lock
    `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
  Returns:
    `true` if the lock could be acquired at the time this method was called
  See Also:
    `MultiLevelLock2.test(Object, int, int)`

### has

    public boolean has(Object ownerId,
                       int lockLevel)

  Description copied from interface: `MultiLevelLock2`
  Tests if a certain lock level is owned by an owner.

  Specified by:
    `has` in interface `MultiLevelLock2`
  Parameters:
    `ownerId` - a unique id identifying the entity that wants to check a certain lock level on this lock
    `lockLevel` - the lock level to test
  Returns:
    `true` if the lock could be acquired at the time this method was called
  See Also:
    `MultiLevelLock2.has(Object, int)`

### 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

  Throws:
    `InterruptedException`
  See Also:
    `acquire(Object, int, boolean, int, boolean, long)`

### acquire

    public boolean acquire(Object ownerId,
                           int targetLockLevel,
                           boolean preferred,
                           long timeoutMSecs)
                    throws InterruptedException

  Tries to blockingly acquire a lock which can be preferred.

  Throws:
    `InterruptedException`
  Since:
    1.1
  See Also:
    `acquire(Object, int, boolean, int, boolean, long)`

### acquire

    public boolean acquire(Object ownerId,
                           int targetLockLevel,
                           boolean wait,
                           int compatibility,
                           boolean preferred,
                           long timeoutMSecs)
                    throws InterruptedException

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

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

### registerWaiter

    protected void registerWaiter(GenericLock.LockOwner waitingOwner)

### unregisterWaiter

    protected void unregisterWaiter(GenericLock.LockOwner waitingOwner)

### release

    public boolean 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
  Returns:
    `true` if the lock actually was released, `false` in case there was no lock held by the owner
  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 GenericLock.LockOwner getMaxLevelOwner()

### getMaxLevelOwner

    protected GenericLock.LockOwner getMaxLevelOwner(GenericLock.LockOwner reentrantOwner,
                                                     boolean preferred)

### getMaxLevelOwner

    protected GenericLock.LockOwner getMaxLevelOwner(int supportLockLevel,
                                                     boolean preferred)

### getMaxLevelOwner

    protected GenericLock.LockOwner getMaxLevelOwner(GenericLock.LockOwner reentrantOwner,
                                                     int supportLockLevel,
                                                     boolean preferred)

### setLockLevel

    protected void setLockLevel(Object ownerId,
                                GenericLock.LockOwner lock,
                                int targetLockLevel,
                                int compatibility,
                                boolean intention)

### tryLock

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

### tryLock

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

### isCompatible

    protected boolean isCompatible(int targetLockLevel,
                                   int currentLockLevel)

### getConflictingOwners

    protected Set getConflictingOwners(Object ownerId,
                                       int targetLockLevel,
                                       int compatibility)

### getConflictingWaiters

    protected Collection getConflictingWaiters(Object ownerId)

### getConflictingOwners

    protected Set getConflictingOwners(GenericLock.LockOwner myOwner,
                                       Collection ownersToTest)

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.