org.exolab.castor.persist
Class ObjectLock

java.lang.Object
  extended by org.exolab.castor.persist.ObjectLock
All Implemented Interfaces:
DepositBox

public final class ObjectLock
extends java.lang.Object
implements DepositBox

Read/write locks and lock synchronization on an object. Each object is required to have one ObjectLock which at any given time may be unlocked, write locked by one transaction, or read locked by one or more transactions.

In order to obtain a lock, the transaction must call one of the acquire, passing itself, the lock type and the lock timeout. The transaction must attempt to obtain only one lock at any given time by synchronizing all calls to one of the acquire. If the transaction has acquired a read lock it may attempt to re-acquire the read lock. If the transaction attempts to acquire a write lock the lock will be upgraded.

A read lock cannot be acquired while there is a write lock on the object, and a write lock cannot be acquired while there is one or more read locks. 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 delete while waiting for the lock, ObjectDeletedException is thrown.

When the lock is acquired, the locked object is returned.

The transaction must call release(org.castor.persist.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.castor.persist.TransactionContext).

If the object has been deleted, the transaction must call delete(org.castor.persist.TransactionContext) instead of release(org.castor.persist.TransactionContext).

Version:
$Revision: 7951 $ $Date: 2006-04-25 15:08:23 -0600 (Tue, 25 Apr 2006) $
Author:
Assaf Arkin, Thomas Yip
See Also:
TransactionContext

Field Summary
protected static short ACTION_CREATE
           
protected static short ACTION_READ
           
protected static short ACTION_UPDATE
           
protected static short ACTION_WRITE
           
 
Constructor Summary
ObjectLock(OID oid)
          Create a new lock for the specified object.
ObjectLock(OID oid, java.lang.Object[] object, long timeStamp)
           
 
Method Summary
 void expire()
          Indicate that object needs to be expired from the cache.
 void expired()
          Indicate that object has been removed from the cache.
 java.lang.Object[] getObject()
           
 java.lang.Object[] getObject(TransactionContext tx)
          Get the object from the DespositBox, only the transaction have the read or write lock can get it.
 OID getOID()
          Return the object's OID.
 long getTimeStamp()
          Get the time of the most recent call on setObject(Object)}.
 void setObject(TransactionContext tx, java.lang.Object[] object, long timeStamp)
          Set an object into the DespositBox, only a transaction has the write lock may call it method or IllegalArgumentException will be thrown.
 void setTimeStamp(long timeStamp)
          Set new timestamp for this object.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ACTION_READ

protected static final short ACTION_READ
See Also:
Constant Field Values

ACTION_WRITE

protected static final short ACTION_WRITE
See Also:
Constant Field Values

ACTION_CREATE

protected static final short ACTION_CREATE
See Also:
Constant Field Values

ACTION_UPDATE

protected static final short ACTION_UPDATE
See Also:
Constant Field Values
Constructor Detail

ObjectLock

public ObjectLock(OID oid)
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 one of the acquire.

Parameters:
oid - The object to create a lock for

ObjectLock

public ObjectLock(OID oid,
                  java.lang.Object[] object,
                  long timeStamp)
Method Detail

getOID

public OID getOID()
Return the object's OID.

Specified by:
getOID in interface DepositBox
Returns:
the object's OID.

getObject

public java.lang.Object[] getObject()

expire

public void expire()
Indicate that object needs to be expired from the cache.


expired

public void expired()
Indicate that object has been removed from the cache. Perform any post expiration cleanup. In particular, remove the reference to any saved cached objects.


setObject

public void setObject(TransactionContext tx,
                      java.lang.Object[] object,
                      long timeStamp)
Description copied from interface: DepositBox
Set an object into the DespositBox, only a transaction has the write lock may call it method or IllegalArgumentException will be thrown.

Specified by:
setObject in interface DepositBox
Parameters:
tx - the transaction in action
object - to be store into deposit box
timeStamp - to be stored into deposit box

getObject

public java.lang.Object[] getObject(TransactionContext tx)
Description copied from interface: DepositBox
Get the object from the DespositBox, only the transaction have the read or write lock can get it.

Specified by:
getObject in interface DepositBox
Parameters:
tx - the transaction in action
Returns:
An object instance.

getTimeStamp

public long getTimeStamp()
Description copied from interface: DepositBox
Get the time of the most recent call on setObject(Object)}.

Specified by:
getTimeStamp in interface DepositBox
Returns:
The timestamp of this object.

setTimeStamp

public void setTimeStamp(long timeStamp)
Description copied from interface: DepositBox
Set new timestamp for this object.

Specified by:
setTimeStamp in interface DepositBox
Parameters:
timeStamp - The new timestamp for this object.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object


Copyright © 2011. All Rights Reserved.