org.exolab.castor.persist

Class ObjectLock

Implemented Interfaces:
DepositBox

(package private) 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(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(TransactionContext).

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

Version:
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:46 $
Authors:
Assaf Arkin
Thomas Yip
See Also:
TransactionContext

Nested Class Summary

(package private) static class
ObjectLock.LinkedTx
Object uses to hold a linked list of transactions holding write locks or waiting for a read/write lock.

Field Summary

(package private) static short
ACTION_CREATE
(package private) static short
ACTION_READ
(package private) static short
ACTION_UPDATE
(package private) static short
ACTION_WRITE
(package private) static boolean
TRACE
(package private) static int
idcount
(package private) static int[]
lock

Constructor Summary

ObjectLock(OID oid)
Create a new lock for the specified object.

Method Summary

(package private) void
acquireCreateLock(TransactionContext tx)
(package private) void
acquireLoadLock(TransactionContext tx, boolean write, int timeout)
(package private) void
acquireUpdateLock(TransactionContext tx, int timeout)
(package private) void
confirm(TransactionContext tx, boolean succeed)
(package private) void
delete(TransactionContext tx)
Informs the lock that the object has been deleted by the transaction holding the write lock.
(package private) void
enter()
Indicate that a transaction is interested in this lock.
(package private) OID
getOID()
Return the object's OID.
Object
getObject(TransactionContext tx)
long
getTimeStamp()
(package private) boolean
hasLock(TransactionContext tx, boolean write)
Returns true if the transaction holds a read or write lock on the object.
(package private) void
invalidate(TransactionContext tx)
(package private) boolean
isDisposable()
Return true if this object can be safely disposed.
(package private) boolean
isEntered()
Return true if there is any transaction called , but not yet called leave.
(package private) boolean
isExclusivelyOwned(TransactionContext tx)
(package private) boolean
isFree()
Return true if and only if this lock can be safely disposed
(package private) void
leave()
Indicate that a transaction is not interested to change the state of this lock anymore.
(package private) void
release(TransactionContext tx)
Releases a lock on the object previously acquired.
(package private) void
setOID(OID oid)
Set OID of this lock to new value.
void
setObject(TransactionContext tx, Object object)
String
toString()
(package private) void
upgrade(TransactionContext tx, int timeout)
Acquires a lock on the object on behalf of the specified transaction.

Field Details

ACTION_CREATE

(package private) static final short ACTION_CREATE
Field Value:
3

ACTION_READ

(package private) static final short ACTION_READ
Field Value:
1

ACTION_UPDATE

(package private) static final short ACTION_UPDATE
Field Value:
4

ACTION_WRITE

(package private) static final short ACTION_WRITE
Field Value:
2

TRACE

(package private) static final boolean TRACE
Field Value:
false

idcount

(package private) static int idcount

lock

(package private) static final int[] lock

Constructor Details

ObjectLock

(package private)  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:

Method Details

acquireCreateLock

(package private)  void acquireCreateLock(TransactionContext tx)
            throws LockNotGrantedException

acquireLoadLock

(package private)  void acquireLoadLock(TransactionContext tx,
                                        boolean write,
                                        int timeout)
            throws LockNotGrantedException,
                   ObjectDeletedWaitingForLockException

acquireUpdateLock

(package private)  void acquireUpdateLock(TransactionContext tx,
                                          int timeout)
            throws LockNotGrantedException,
                   ObjectDeletedException,
                   ObjectDeletedWaitingForLockException

confirm

(package private)  void confirm(TransactionContext tx,
                                boolean succeed)

delete

(package private)  void delete(TransactionContext tx)
Informs the lock that the object has been deleted by the transaction holding the write 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

enter

(package private)  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 acquire, update or relase.) It method should be synchronized externally to avoid race condition. enter and leave should be called exactly the same number of time.

getOID

(package private)  OID getOID()
Return the object's OID.

getObject

public Object getObject(TransactionContext tx)
Specified by:
getObject in interface DepositBox

getTimeStamp

public long getTimeStamp()
Specified by:
getTimeStamp in interface DepositBox

hasLock

(package private)  boolean hasLock(TransactionContext tx,
                                   boolean write)
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
write - True if must have a write lock
Returns:
True if the transaction has a lock on this object

invalidate

(package private)  void invalidate(TransactionContext tx)

isDisposable

(package private)  boolean isDisposable()
Return true if this object can be safely disposed. An ObjectLock can be safely disposed if and only if the no transaction is holding any lock, nor any transaction isEntered.

isEntered

(package private)  boolean isEntered()
Return true if there is any transaction called , but not yet called leave.

isExclusivelyOwned

(package private)  boolean isExclusivelyOwned(TransactionContext tx)

isFree

(package private)  boolean isFree()
Return true if and only if this lock can be safely disposed
Returns:
True if no lock and no waiting

leave

(package private)  void leave()
Indicate that a transaction is not interested to change the state of this lock anymore. (ie, will not call either acquire update, release or delete.) It method should be synchronized externally.

release

(package private)  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

setOID

(package private)  void setOID(OID oid)
Set OID of this lock to new value.

setObject

public void setObject(TransactionContext tx,
                      Object object)
Specified by:
setObject in interface DepositBox

toString

public String toString()

upgrade

(package private)  void upgrade(TransactionContext tx,
                                int timeout)
            throws LockNotGrantedException,
                   ObjectDeletedWaitingForLockException
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 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.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
ObjectDeletedWaitingForLockException - The object has been deleted while waiting for the lock

Intalio Inc. (C) 1999-2003. All rights reserved http://www.intalio.com