org.jboss.cache.lock
Class IdentityLock

java.lang.Object
  extended by 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)


Copyright 1998-2005 JBoss Inc . All Rights Reserved.