org.exolab.core.foundation
Class Lock

java.lang.Object
  extended by org.exolab.core.foundation.Lock

public final class Lock
extends java.lang.Object

Exclusive lock and lock synchronization on an object. Each object (session, entity bean, etc) is required to have one Lock which is served as an exclusive lock. Only one transaction can acquire the lock at any given time, but multiple transactions may be waiting to acquire a lock.

In order to obtain a lock, the transaction must call acquire(org.exolab.core.foundation.TransactionContext, int) passing itself and the lock timeout. The transaction must attempt to obtain only one lock at any given time by synchronizing all calls to acquire(org.exolab.core.foundation.TransactionContext, int).

Locks implement reference counting. The transaction may acquire the same lock any number of times, but must also release it the same number of times (in no particular order).

If a lock cannot be acquired, the transaction will hold until the lock is available or timeout occurs. If timeout occured (or a dead lock has been detected), LockNotGrantedException is thrown. If the object has been deleted while waiting for the lock, ObjectDeletedException is thrown.

When the lock is acquired, acquire(org.exolab.core.foundation.TransactionContext, int) will return the locked object.

The transaction must call release(org.exolab.core.foundation.TransactionContext) when the lock is no longer required, allowing other transactions to obtain a lock. The transaction must release all references to the object prior to calling release(org.exolab.core.foundation.TransactionContext).

If the object has been deleted, the transaction must call delete(org.exolab.core.foundation.TransactionContext) instead of release(org.exolab.core.foundation.TransactionContext).

Version:
$Revision: 1.6 $ $Date: 2003/06/09 06:28:39 $
Author:
Assaf Arkin
See Also:
TransactionContext

Constructor Summary
Lock(PersistentCapableIfc obj)
          Create a new lock for the specified object.
 
Method Summary
 PersistentCapableIfc acquire(TransactionContext tx, int timeout)
          Acquires a lock on the object on behalf of the specified transaction.
 boolean anyTxWaiting()
          Check to see if the current transaction context owns the lock and that no other transaction is queued waiting for it.
 void delete(TransactionContext tx)
          Informs the lock that the object has been deleted by the transaction holding the lock.
 PersistentCapableIfc getObject()
          Return a reference to the object that this lock guards
 boolean hasLock(TransactionContext tx)
          Returns true if the transaction holds a lock on the object.
 void release(TransactionContext tx)
          Releases a lock on the object previously acquired with acquire(org.exolab.core.foundation.TransactionContext, int).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Lock

public Lock(PersistentCapableIfc obj)
Create a new lock for the specified object. Must not create two locks for the same object. This will be the object returned from a successful call to acquire(org.exolab.core.foundation.TransactionContext, int).

Parameters:
obj - The object to create a lock for
Method Detail

hasLock

public boolean hasLock(TransactionContext tx)
Returns true if the transaction holds a lock on the object. This method is an efficient mean to determine whether a lock is required, or if the object is owned by the transaction.

Parameters:
tx - The transaction
Returns:
True if the transaction has a lock on this object

getObject

public PersistentCapableIfc getObject()
Return a reference to the object that this lock guards

Returns:
PersistentCapableIfc

acquire

public PersistentCapableIfc acquire(TransactionContext tx,
                                    int timeout)
                             throws LockNotGrantedException,
                                    ObjectDeletedWaitingForLockException
Acquires a lock on the object on behalf of the specified transaction. If the lock cannot be acquired immediately, the thread will block until the lock is made available or the timeout has elapsed. If the timeout has elapsed or a dead lock has been detected, a LockNotGrantedException is thrown. If the object has been deleted while waiting for a lock, a ObjectDeletedException is thrown. To prevent dead locks, a transaction must only call this method for any given object from a single thread and must mark the lock it is trying to acquire and return it from a call to TransactionContext#getWaitingOnLock if the call to this method has not returned yet. If this method has been called multiple times by the same transaction, then release(org.exolab.core.foundation.TransactionContext) must be called the same number of times to release the lock.

Parameters:
tx - The transaction requesting the lock
timeout - Timeout waiting to acquire lock (in milliseconds), zero for no waiting
Returns:
The locked object
Throws:
LockNotGrantedException - Lock could not be granted in the specified timeout or a dead lock has been detected
ObjectDeletedWaitingForLockException - The object has been deleted while waiting for the lock

release

public void release(TransactionContext tx)
Releases a lock on the object previously acquired with acquire(org.exolab.core.foundation.TransactionContext, int). This method must be called one time for each time acquire(org.exolab.core.foundation.TransactionContext, int) was called. After the lock is fully released, other transactions might acquire it.

Parameters:
tx - The transaction that holds the lock

anyTxWaiting

public boolean anyTxWaiting()
Check to see if the current transaction context owns the lock and that no other transaction is queued waiting for it.

Returns:
boolean true if no other waiters and false otherwise

delete

public void delete(TransactionContext tx)
Informs the lock that the object has been deleted by the transaction holding the lock. The lock on the object is released and all transactions waiting for a lock will terminate with an ObjectDeletedException.

Parameters:
tx - The transaction that holds the lock
Throws:
java.lang.RuntimeException - Attempt to delete object without acquiring a write lock


Copyright © 1999-2012 The Exolab Group. All Rights Reserved.