Class ObjectLock
- All Implemented Interfaces:
DepositBox
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,
invalid reference
ObjectDeletedException
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static class
Object uses to hold a linked list of transactions holding write locks or waiting for a read/write lock. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected static final short
protected static final short
protected static final short
protected static final short
-
Constructor Summary
ConstructorsConstructorDescriptionObjectLock
(OID oid) Create a new lock for the specified object.ObjectLock
(OID oid, Object[] object, long version) -
Method Summary
Modifier and TypeMethodDescription(package private) void
(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
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.Object[]
Object[]
Get the object from the DespositBox, only the transaction have the read or write lock can get it.getOID()
Return the object's OID.long
(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
(package private) boolean
Return true if this object can be safely disposed.(package private) boolean
(package private) boolean
(package private) boolean
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
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.(package private) void
Set OID of this lock to new value.void
setVersion
(long version) Sets the new version of this object.toString()
(package private) void
upgrade
(TransactionContext tx, int timeout) Acquires a lock on the object on behalf of the specified transaction.
-
Field Details
-
ACTION_READ
protected static final short ACTION_READ- See Also:
-
ACTION_WRITE
protected static final short ACTION_WRITE- See Also:
-
ACTION_CREATE
protected static final short ACTION_CREATE- See Also:
-
ACTION_UPDATE
protected static final short ACTION_UPDATE- See Also:
-
-
Constructor Details
-
ObjectLock
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
-
-
Method Details
-
getOID
Return the object's OID.- Specified by:
getOID
in interfaceDepositBox
- Returns:
- the object's OID.
-
setOID
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() -
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
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 transactionwrite
- 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
-
isExpired
boolean isExpired()Return true if this entry has been expired from the cache. -
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
- Throws:
LockNotGrantedException
-
acquireUpdateLock
- Throws:
LockNotGrantedException
-
setObject
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 interfaceDepositBox
- Parameters:
tx
- the transaction in actionobject
- to be store into deposit boxversion
- of the object to be stored
-
getObject
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 interfaceDepositBox
- Parameters:
tx
- the transaction in action- Returns:
- An object instance.
-
getVersion
public long getVersion()- Specified by:
getVersion
in interfaceDepositBox
- 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 interfaceDepositBox
- Parameters:
version
- a timestamp.
-
confirm
-
upgrade
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, aLockNotGrantedException
is thrown. If the object has been deleted while waiting for a lock, ainvalid reference
ObjectDeletedException
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 locktimeout
- 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 detectedObjectDeletedWaitingForLockException
- The object has been deleted while waiting for the lock
-
release
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
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 aninvalid reference
ObjectDeletedException
- Parameters:
tx
- The transaction that holds the lock- Throws:
RuntimeException
- Attempt to delete object without acquiring a write lock
-
invalidate
-
toString
-