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

## org.jboss.cache.lock
Class IdentityLock

    java.lang.Object
      org.jboss.cache.lock.IdentityLock

    public class IdentityLock

extends java.lang.Object

Lock object which grants and releases locks, and associates locks with owners. The methods to acquire and release a lock require an owner (Object). When a lock is acquired, we store the current owner with the lock. When the same owner (but possibly running in a different thread) wants to acquire the lock, it is immediately granted. When an owner different from the one currently owning the lock wants to release the lock, we do nothing (no-op).

Consider the following example:

     FIFOSemaphore lock=new FIFOSemaphore(1);
     lock.acquire();
     lock.acquire();
     lock.release();

This would block on the second `acquire()` (although we currently already hold the lock) because the lock only has 1 permit. So `IdentityLock` will allow the following code to work properly:

     IdentityLock lock=new IdentityLock();
     lock.readLock().acquire(this, timeout);
     lock.writeLock().acquire(this, timeout);
     lock.release(this);

If the owner is null, then the current thread is taken by default. This allow the following code to work:

     IdentityLock lock=new IdentityLock();
     lock.readLock().attempt(null, timeout);
     lock.writeLock().attempt(null, timeout);
     lock.release(null);

Note that the Object given as owner is required to implement `Object.equals(java.lang.Object)`. For a use case see the examples in the testsuite.

Version:
  $Revision: 1.12 $
Author:
  Bela Ban Apr 11, 2003, Ben Wang July 2003

Constructor Summary
`IdentityLock(IsolationLevel level)` For testing only
`IdentityLock(TreeCache cache)` Constructs a new lock.
`IdentityLock(TreeCache cache, Fqn fqn)` Constructs a new lock.

Method Summary
`boolean` | `acquireReadLock(java.lang.Object caller, long timeout)` Acquire a read lock with a timeout period of `timeout` milliseconds.
`boolean` | `acquireWriteLock(java.lang.Object caller, long timeout)` Acquire a write lock with a timeout of `timeout` milliseconds.
`Fqn` | `getFqn()` Returns the FQN for this lock, may be `null`.
`java.util.Set` | `getReaderOwners()` Return a copy of the reader lock owner in List.
`java.lang.Object` | `getWriterOwner()` Return the writer lock owner object.
`boolean` | `isLocked()` Check if there is a read or write lock
`boolean` | `isOwner(java.lang.Object o)` Am I a lock owner?
`boolean` | `isReadLocked()` Check if there is a read lock.
`boolean` | `isWriteLocked()` Check if there is a write lock.
`void` | `release(java.lang.Object caller)` Release the lock held by the owner.
`void` | `releaseAll()` Release all locks associated with this instance.
`void` | `releaseForce()` Same as releaseAll now.
`java.lang.String` | `toString()`
`java.lang.String` | `toString(boolean print_lock_details)`
`void` | `toString(java.lang.StringBuffer sb)`
`void` | `toString(java.lang.StringBuffer sb, boolean print_lock_details)`

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

Constructor Detail

### IdentityLock

    public IdentityLock(TreeCache cache,
                        Fqn fqn)

  Constructs a new lock.

  Parameters:
    `cache` - cache for deciding lock strategy
    `fqn` - ignored.

### IdentityLock

    public IdentityLock(TreeCache cache)

  Constructs a new lock.

  Parameters:
    `cache` - cache for deciding lock strategy TODO remove this constructor

### IdentityLock

    public IdentityLock(IsolationLevel level)

  For testing only

Method Detail

### getFqn

    public Fqn getFqn()

  Returns the FQN for this lock, may be `null`.

### getReaderOwners

    public java.util.Set getReaderOwners()

  Return a copy of the reader lock owner in List. Size is zero is not available. Note that this list is synchronized.

  Returns:
    Set of readers

### getWriterOwner

    public java.lang.Object getWriterOwner()

  Return the writer lock owner object. Null if not available.

  Returns:
    Object owner

### acquireWriteLock

    public boolean acquireWriteLock(java.lang.Object caller,
                                    long timeout)
                             throws LockingException,
                                    TimeoutException,
                                    java.lang.InterruptedException

  Acquire a write lock with a timeout of `timeout` milliseconds. Note that if the current owner owns a read lock, it will be upgraded automatically. However, if upgrade fails, i.e., timeout, the read lock will be released automatically.

  Parameters:
    `caller` - Can't be null.
    `timeout` -
  Returns:
    boolean True if lock was acquired and was not held before, false if lock was held
  Throws:
    `LockingException`
    `TimeoutException`
    `java.lang.InterruptedException`

### acquireReadLock

    public boolean acquireReadLock(java.lang.Object caller,
                                   long timeout)
                            throws LockingException,
                                   TimeoutException,
                                   java.lang.InterruptedException

  Acquire a read lock with a timeout period of `timeout` milliseconds.

  Parameters:
    `caller` - Can't be null.
    `timeout` -
  Returns:
    boolean True if lock was acquired and was not held before, false if lock was held
  Throws:
    `LockingException`
    `TimeoutException`
    `java.lang.InterruptedException`

### release

    public void release(java.lang.Object caller)

  Release the lock held by the owner.

  Parameters:
    `caller` - Can't be null.

### releaseAll

    public void releaseAll()

  Release all locks associated with this instance.

### releaseForce

    public void releaseForce()

  Same as releaseAll now.

### isReadLocked

    public boolean isReadLocked()

  Check if there is a read lock.

### isWriteLocked

    public boolean isWriteLocked()

  Check if there is a write lock.

### isLocked

    public boolean isLocked()

  Check if there is a read or write lock

### isOwner

    public boolean isOwner(java.lang.Object o)

  Am I a lock owner?

  Parameters:
    `o` -

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

### toString

    public java.lang.String toString(boolean print_lock_details)

### toString

    public void toString(java.lang.StringBuffer sb)

### toString

    public void toString(java.lang.StringBuffer sb,
                         boolean print_lock_details)

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

Copyright © 1998-2005 JBoss Inc . All Rights Reserved.