org.exolab.castor.persist
Class ObjectLock

java.lang.Object
  org.exolab.castor.persist.ObjectLock

All Implemented Interfaces:

DepositBox

public final class ObjectLock
extends 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: 8294 $ $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, Object[] object, long version)

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.
Object[]	getObject()
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	getVersion()
void	setObject(TransactionContext tx, Object[] object, long version) Set an object into the DespositBox, only a transaction has the write lock may call it method or IllegalArgumentException will be thrown.
void	setVersion(long version) Sets the new version of this object.
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,
                  Object[] object,
                  long version)

Method Detail

getOID

public OID getOID()

Return the object's OID.

Specified by:

getOID in interface DepositBox

Returns:

the object's OID.

getObject

public 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,
                      Object[] object,
                      long version)

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

version - of the object to be stored

getObject

public 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.

getVersion

public long getVersion()

Specified by:

getVersion in interface DepositBox

Returns:

the version (a timestamp) of the last setObject(object) call.

setVersion

public void setVersion(long version)

Description copied from interface: DepositBox

Sets the new version of this object.

Specified by:

setVersion in interface DepositBox

Parameters:

version - a timestamp.

toString

public String toString()

Overrides:

toString in class Object