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 the acquireLock. 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 occurred (or a dead lock has been detected), LockNotGrantedException is thrown. If the object has been delete while waiting for the lock, ObjectDeletedWaitingForLockException 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) first, then release(org.castor.persist.TransactionContext).

Version:

$Revision: 9042 $ $Date: 2011-08-16 18:41:15 +0200 (Di, 16 Aug 2011) $

Author:

Assaf Arkin, Thomas Yip, Wensheng Dou, Ralf Joachim

Constructor Summary

protected	ObjectLock(OID oid) Create a new lock for the specified object.
protected	ObjectLock(OID oid, Object[] object, long version) Create a new lock for the specified object.

Method Summary

protected void	acquireLock(TransactionContext tx, LockAction action, int timeout) The TransactionContext tries to acquire a lock for LockAction.
void	confirm(TransactionContext tx, boolean succeed) Confirm the lock.
void	delete(TransactionContext tx) Informs the lock that the object has been deleted by the transaction holding the write lock.
protected void	enter() Indicate that a transaction is interested in this lock.
void	expire() Indicate that object needs to be expired from the cache.
protected 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() Get OID of the entity locked.
long	getVersion()
protected boolean	hasLock(TransactionContext tx) Returns true if the transaction holds a read or write lock on the object.
protected boolean	hasWriteLock(TransactionContext tx) Returns true if the transaction holds a write lock on the object.
void	invalidate(TransactionContext tx) Informs the lock that the object has been invalidated by the transaction holding the write lock.
protected boolean	isDisposable()
protected boolean	isEntered() Are there transactions interested in this lock?
protected boolean	isExclusivelyOwned(TransactionContext tx)
protected boolean	isExpired() Has this entity been expired from the cache?
protected void	leave() Indicate that a transaction is not interested to change the state of this lock anymore (ie, will not call either acquireLock, delete, upgrade or release).
void	release(TransactionContext tx) Releases a lock on the object previously acquired.
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.
protected void	setOID(OID oid) Set OID of the entity locked.
void	setVersion(long version) Set the version of the object.
String	toString()
protected void	upgrade(TransactionContext tx, int timeout) Acquires a lock on the object on behalf of the specified transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectLock

protected 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

protected ObjectLock(OID oid,
                     Object[] object,
                     long version)

Create a new lock for the specified object.

Parameters:

oid - the object to create a lock for

object - the values of the entity

version - the version of the entity

Method Detail

getOID

public OID getOID()

Get OID of the entity locked.

Specified by:

getOID in interface DepositBox

Returns:

OID of the entity locked.

setOID

protected void setOID(OID oid)

Set OID of the entity locked.

Parameters:

oid - OID of the entity locked.

getObject

public Object[] getObject()

Returns:

the actual values of the entity

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

Returns:

the actual values of the entity, if the tx has the lock

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 TransactionContext which want to set the object

object - The actual object

version - the version of the object

getVersion

public long getVersion()

Specified by:

getVersion in interface DepositBox

Returns:

the version of the object

setVersion

public void setVersion(long version)

Set the version of the object.

Specified by:

setVersion in interface DepositBox

Parameters:

version - the new version

enter

protected void enter()

Indicate that a transaction is interested in this lock. A transaction should call this method if it is going to change the state of this lock (by calling acquireLock, delete, upgrade, release.) The method should be synchronized externally to avoid race condition. enter and leave should be called exactly the same number of time.

leave

protected void leave()

Indicate that a transaction is not interested to change the state of this lock anymore (ie, will not call either acquireLock, delete, upgrade or release). The method should be synchronized externally.

isEntered

protected boolean isEntered()

Are there transactions interested in this lock?

Returns:

true if there is any transaction called enter(), but not yet called leave().

acquireLock

protected void acquireLock(TransactionContext tx,
                           LockAction action,
                           int timeout)
                    throws LockNotGrantedException

The TransactionContext tries to acquire a lock for LockAction.

Parameters:

tx - The TransactionContext

action - The LockAction

timeout - The timeout for acquiring the lock

Throws:

LockNotGrantedException - If the lock is not granted

confirm

public void confirm(TransactionContext tx,
                    boolean succeed)

Confirm the lock.

Parameters:

tx - The transaction

succeed - whether the transaction's process is OK

upgrade

protected void upgrade(TransactionContext tx,
                       int timeout)
                throws LockNotGrantedException

Acquires a lock on the object on behalf of the specified transaction. A write lock will be acquired only if there are no read/write locks on the object; only one write lock may be in effect. A read lock will be acquired only if there is no write lock on the object; multiple read locks are allowed. 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 ObjectDeletedWaitingForLockException 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.getWaitOnLock() if the call to this method has not returned yet. If a read lock is available for the transaction and a write lock is requested, the read lock is cancelled whether or not the write is acquired.

Parameters:

tx - The transaction requesting the lock

timeout - Timeout waiting to acquire lock (in milliseconds), zero for no waiting

Throws:

LockNotGrantedException - Lock could not be granted in the specified timeout or a dead lock has been detected

release

public void release(TransactionContext tx)

Releases a lock on the object previously acquired. A write lock cannot be downgraded into a read lock and the transaction loses its lock on the object. Other transactions are allowed to acquire a read/write lock on the object.

Parameters:

tx - The transaction that holds the lock

delete

public void delete(TransactionContext tx)

Informs the lock that the object has been deleted by the transaction holding the write lock.

Parameters:

tx - The transaction that holds the lock

invalidate

public void invalidate(TransactionContext tx)

Informs the lock that the object has been invalidated by the transaction holding the write lock.

Parameters:

tx - The transaction that holds the lock

expire

public void expire()

Indicate that object needs to be expired from the cache.

expired

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

isExpired

protected boolean isExpired()

Has this entity been expired from the cache?

Returns:

true if this entity has been expired from the cache.

isDisposable

protected boolean isDisposable()

Returns:

true if this object can be safely disposed. An ObjectLock can be safely disposed if and only if the no transaction is holding or waiting any lock, nor any transaction isEntered.

hasLock

protected boolean hasLock(TransactionContext tx)

Returns true if the transaction holds a read or write 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.

hasWriteLock

protected boolean hasWriteLock(TransactionContext tx)

Returns true if the transaction holds a write 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 write lock on this object.

isExclusivelyOwned

protected boolean isExclusivelyOwned(TransactionContext tx)

Parameters:

tx - The transaction.

Returns:

true if the transaction has the lock exclusively on this object.

toString

public String toString()

Overrides:

toString in class Object

Returns:

the lock's information.