ObjectLock (Castor JavaDoc)

java.lang.Object
- 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: 8294 $ $Date: 2006-04-25 15:08:23 -0600 (Tue, 25 Apr 2006) $

Author:

Assaf Arkin, Thomas Yip

See Also:

TransactionContext

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`(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

Fields
Modifier and Type	Field	Description
`protected static short`	`ACTION_CREATE`
`protected static short`	`ACTION_READ`
`protected static short`	`ACTION_UPDATE`
`protected static short`	`ACTION_WRITE`

Constructor Summary

Constructors
Constructor	Description
`ObjectLock(OID oid)`	Create a new lock for the specified object.
`ObjectLock(OID oid, java.lang.Object[] object, long version)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`(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.
`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`	`getVersion()`
`(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 `enter()`, but not yet called `leave()`.
`(package private) boolean`	`isExclusivelyOwned(TransactionContext tx)`
`(package private) boolean`	`isExpired()`	Return true if this entry has been expired from the cache.
`(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.
`void`	`setObject(TransactionContext tx, java.lang.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.
`(package private) void`	`setOID(OID oid)`	Set OID of this lock to new value.
`void`	`setVersion(long version)`	Sets the new version of this object.
`java.lang.String`	`toString()`
`(package private) 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

- 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 version)
```
- Method Detail
  - getOID
```
public OID getOID()
```
    Return the object's OID.
    
    Specified by:
    
    getOID in interface DepositBox
    
    Returns:
    
    the object's OID.
  - setOID
```
void setOID(OID oid)
```
    Set OID of this lock to new value.
  - enter
```
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.
  - leave
```
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.
  - isEntered
```
boolean isEntered()
```
    Return true if there is any transaction called enter(), but not yet called leave().
  - isDisposable
```
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.
  - hasLock
```
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
  - isFree
```
boolean isFree()
```
    Return true if and only if this lock can be safely disposed.
    
    Returns:
    
    True if no lock and no waiting.
  - isExclusivelyOwned
```
boolean isExclusivelyOwned(TransactionContext tx)
```
  - isExpired
```
boolean isExpired()
```
    Return true if this entry has been expired from the cache.
  - 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.
  - acquireLoadLock
```
void acquireLoadLock(TransactionContext tx,
                     boolean write,
                     int timeout)
              throws LockNotGrantedException
```
    Throws:
    
    LockNotGrantedException
  - acquireCreateLock
```
void acquireCreateLock(TransactionContext tx)
                throws LockNotGrantedException
```
    Throws:
    
    LockNotGrantedException
  - acquireUpdateLock
```
void acquireUpdateLock(TransactionContext tx,
                       int timeout)
                throws LockNotGrantedException
```
    Throws:
    
    LockNotGrantedException
  - setObject
```
public void setObject(TransactionContext tx,
                      java.lang.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 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.
  - 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.
  - confirm
```
void confirm(TransactionContext tx,
             boolean succeed)
```
  - upgrade
```
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 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
  - release
```
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
```
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
    
    Throws:
    
    java.lang.RuntimeException - Attempt to delete object without acquiring a write lock
  - invalidate
```
void invalidate(TransactionContext tx)
```
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class ObjectLock

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ACTION_READ

ACTION_WRITE

ACTION_CREATE

ACTION_UPDATE

Constructor Detail

ObjectLock

ObjectLock

Method Detail

getOID

setOID

enter

leave

isEntered

isDisposable

hasLock

isFree

isExclusivelyOwned

isExpired

getObject

expire

expired

acquireLoadLock

acquireCreateLock

acquireUpdateLock

setObject

getObject

getVersion

setVersion

confirm

upgrade

release

delete

invalidate

toString