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 ReadWriteUpgradeLock

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

All Implemented Interfaces:
  MultiLevelLock, MultiLevelLock2

public class ReadWriteUpgradeLock
extends GenericLock

Convenience implementation of a read/write lock with an option for upgrade based on `ReadWriteUpgradeLockLock`.
Reads are shared which means there can be any number of concurrent read accesses allowed by this lock. Writes are exclusive. This means when there is a write access no other access neither read nor write are allowed by this lock.

The idea (as explained by Jim LoVerde) on an upgrade lock is that only one owner can hold an upgrade lock, but while that is held, it is possible for read locks to exist and/or be obtained, and when the request is made to upgrade to a write lock by the same owner, the lock manager prevents additional read locks until the write lock can be aquired.

In this sense the write lock becomes preferred over all other locks when it gets upgraded from a upgrate lock. Preferred means that if it has to wait and others wait as well it will be served before all other none preferred locking requests.

Calls to `acquireRead(Object, long)`, `acquireUpgrade(Object, long)` and `acquireWrite(Object, long)` are blocking and reentrant. Blocking means they will wait if they can not acquire the descired access, reentrant means that a lock request by a specific owner will always be compatible with other accesses on this lock by the same owner. E.g. if you already have a lock for writing and you try to acquire write access again you will not be blocked by this first lock, while others of course will be. This is the natural way you already know from Java monitors and synchronized blocks.

Since:
  1.1
Version:
  $Revision$
See Also:
  `GenericLock`, `ReadWriteLock`, `ReadWriteUpgradeLockManager`

Nested Class Summary

Nested classes inherited from class org.apache.commons.transaction.locking.GenericLock
`GenericLock.LockOwner`

Field Summary
`static int` | `NO_LOCK`
`static int` | `READ_LOCK`
`static int` | `UPGRADE_LOCK`
`static int` | `WRITE_LOCK`

Fields inherited from class org.apache.commons.transaction.locking.GenericLock
`logger, owners, resourceId, waiters, waitingOwners`

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

Constructor Summary
`ReadWriteUpgradeLock(Object resourceId, LoggerFacade logger)` Creates a new read/write/upgrade lock.

Method Summary
`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` | `acquireRead(Object ownerId, long timeoutMSecs)` Tries to acquire a blocking, reentrant read lock.
`boolean` | `acquireUpgrade(Object ownerId, long timeoutMSecs)` Tries to acquire a reentrant upgrade lock on a resource.
`boolean` | `acquireWrite(Object ownerId, long timeoutMSecs)` Tries to acquire a blocking, reentrant write lock.

Methods inherited from class org.apache.commons.transaction.locking.GenericLock
`acquire, acquire, acquire, equals, getConflictingOwners, getConflictingOwners, getConflictingWaiters, getLevelMaxLock, getLevelMinLock, getLockLevel, getMaxLevelOwner, getMaxLevelOwner, getMaxLevelOwner, getMaxLevelOwner, getOwner, getResourceId, has, hashCode, isCompatible, registerWaiter, release, setLockLevel, test, toString, tryLock, tryLock, unregisterWaiter`

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

Field Detail

### NO_LOCK

    public static final int NO_LOCK

See Also:
  Constant Field Values

### READ_LOCK

    public static final int READ_LOCK

See Also:
  Constant Field Values

### UPGRADE_LOCK

    public static final int UPGRADE_LOCK

See Also:
  Constant Field Values

### WRITE_LOCK

    public static final int WRITE_LOCK

See Also:
  Constant Field Values

Constructor Detail

### ReadWriteUpgradeLock

    public ReadWriteUpgradeLock(Object resourceId,
                                LoggerFacade logger)

  Creates a new read/write/upgrade lock.

Parameters:
  `resourceId` - identifier for the resource associated to this lock
  `logger` - generic logger used for all kind of debug logging

Method Detail

### acquireRead

    public boolean acquireRead(Object ownerId,
                               long timeoutMSecs)
                        throws InterruptedException

  Tries to acquire a blocking, reentrant read lock. A read lock is compatible with other read locks, but not with a write lock.

  Parameters:
    `ownerId` - a unique id identifying the entity that wants to acquire a certain lock level on this lock
    `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

### acquireUpgrade

    public boolean acquireUpgrade(Object ownerId,
                                  long timeoutMSecs)
                           throws InterruptedException

  Tries to acquire a reentrant upgrade lock on a resource.

  Parameters:
    `ownerId` - a unique id identifying the entity that wants to acquire a certain lock level on this lock
    `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

### acquireWrite

    public boolean acquireWrite(Object ownerId,
                                long timeoutMSecs)
                         throws InterruptedException

  Tries to acquire a blocking, reentrant write lock. A write lock is incompatible with any another read or write lock and is thus exclusive.

  Parameters:
    `ownerId` - a unique id identifying the entity that wants to acquire a certain lock level on this lock
    `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

### 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`
  Overrides:
    `acquire` in class `GenericLock`
  Throws:
    `InterruptedException`
  See Also:
    `GenericLock.acquire(Object, int, boolean, int, boolean, long)`

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.