org.exolab.castor.persist

Class LockEngine


public final class LockEngine
extends java.lang.Object

LockEngine is a gateway for all the ClassMolders of a persistence storage. It mantains dirty checking cache state and lock, and provides a thread safe enviroment for ClassMolder. LockEngine garantees that no two conflicting operations will be let running concurrently for the same object.

For example, it ensures that exactly one transaction may read (load) exclusively on one object; transaction can not deleted an object while the other is reading it, etc...

It also provides caching for a persistence storage. Different LRU mechanisms can be specified.

User should not create more than one instance of LockEngine for each persistent storage. So that object can be properly locked and ObjectModifiedException can be avoided.

However, if more than one instance of LockEngine or some other external application run concurrently, if the Persistence supports dirty checking, like a fully complaint JDBC Relational Database, proper ObjectModifiedException will be thrown to ensure data consistency.

Version:
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:44 $
Authors:
Assaf Arkin
Thomas Yip

Constructor Summary

LockEngine(MappingResolver mapResolver, PersistenceFactory factory, LogInterceptor logInterceptor)
Construct a new cache engine with the specified mapping table, persistence engine and the log interceptor.

Method Summary

OID
create(TransactionContext tx, OID oid, Object object)
Creates a new object in the persistence storage.
void
delete(TransactionContext tx, OID oid, Object object)
Called at transaction commit time to delete the object.
void
forgetObject(TransactionContext tx, OID oid)
Called at transaction commit or rollback to forget an object and release its locks.
ClassMolder
getClassMolder(Class cls)
Get classMolder which represents the given java data object class Dependent class will not be returned to avoid persistenting a dependent class without
Persistence
getPersistence(Class cls)
HashMap
getXATransactions()
Returns an association between Xid and transactions contexts.
OID
load(TransactionContext tx, OID oid, Object object, AccessMode suggestedAccessMode, int timeout)
Loads an object of the specified type and identity from persistent storage.
OID
load(TransactionContext tx, OID oid, Object object, AccessMode suggestedAccessMode, int timeout, QueryResults results)
void
markCreate(TransactionContext tx, OID oid, Object object)
Mark an object and its related or dependent object to be created
void
markDelete(TransactionContext tx, OID oid, Object object, int timeout)
OID
preStore(TransactionContext tx, OID oid, Object object, int timeout)
Called at transaction commit to store an object that has been loaded during the transaction.
void
releaseLock(TransactionContext tx, OID oid)
Called at transaction commit or rollback to release all locks held on the object.
void
revertObject(TransactionContext tx, OID oid, Object object)
Reverts an object to the cached copy given the object's OID.
void
softLock(TransactionContext tx, OID oid, int timeout)
Acquire a write lock on the object in memory.
void
store(TransactionContext tx, OID oid, Object object)
boolean
update(TransactionContext tx, OID oid, Object object, AccessMode suggestedAccessMode, int timeout)
Updates an existing object to this engine.
void
updateCache(TransactionContext tx, OID oid, Object object)
Update the cached object with changes done to its copy.
void
writeLock(TransactionContext tx, OID oid, int timeout)
Acquire a write lock on the object.

Constructor Details

LockEngine

(package private)  LockEngine(MappingResolver mapResolver,
                              PersistenceFactory factory,
                              LogInterceptor logInterceptor)
            throws MappingException
Construct a new cache engine with the specified mapping table, persistence engine and the log interceptor.
Parameters:
mapResolver - Provides mapping information for objects supported by this cache
factory - Factory for creating persistence engines for each object described in the map
logInterceptor - Log interceptor to use for cache and all its persistence engines
Throws:
MappingException - Indicate that one of the mappings is invalid

Method Details

create

public OID create(TransactionContext tx,
                  OID oid,
                  Object object)
            throws DuplicateIdentityException,
                   PersistenceException,
                   ClassNotPersistenceCapableException
Creates a new object in the persistence storage. The object must not be persistent and must have a unique identity within this engine. If the identity is specified the object is created in persistent storage immediately with the identity. If the identity is not specified, the object is created only when the transaction commits. The object's OID is returned. The OID is guaranteed to be unique for this engine even if no identity was specified.
Parameters:
tx - The transaction context
oid - The identity of the object, or null
object - The newly created object
Returns:
The object's OID
Throws:
DuplicateIdentityException - An object with this identity already exists in persistent storage
PersistenceException - An error reported by the persistence engine
ClassNotPersistenceCapableException - The class is not persistent capable

delete

public void delete(TransactionContext tx,
                   OID oid,
                   Object object)
            throws PersistenceException
Called at transaction commit time to delete the object. Object deletion occurs in three distinct steps:
  • A write lock is obtained on the object to assure it can be deleted and the object is marked for deletion in the transaction context
  • As part of transaction preparation the object is deleted from persistent storage using this method
  • The object is removed from the cache when the transaction completes with a call to forgetObject(TransactionContext,OID)
Parameters:
tx - The transaction context
oid - The object's identity
object - The object type
Throws:
PersistenceException - An error reported by the persistence engine

forgetObject

public void forgetObject(TransactionContext tx,
                         OID oid)
Called at transaction commit or rollback to forget an object and release its locks. Must be called for all objects that were created when the transaction aborts, and for all objects that were deleted when the transaction completes. The transaction is known to have a write lock on the object.
Parameters:
tx - The transaction context
oid - The object OID

getClassMolder

public ClassMolder getClassMolder(Class cls)
Get classMolder which represents the given java data object class Dependent class will not be returned to avoid persistenting a dependent class without

getPersistence

public Persistence getPersistence(Class cls)

getXATransactions

public HashMap getXATransactions()
Returns an association between Xid and transactions contexts. The association is shared between all transactions open against this cache engine through the XAResource interface.

load

public OID load(TransactionContext tx,
                OID oid,
                Object object,
                AccessMode suggestedAccessMode,
                int timeout)
            throws ObjectNotFoundException,
                   LockNotGrantedException,
                   PersistenceException,
                   ClassNotPersistenceCapableException,
                   ObjectDeletedWaitingForLockException
Loads an object of the specified type and identity from persistent storage. In exclusive mode the object is always loaded and a write lock is obtained on the object, preventing concurrent updates. In non-exclusive mode the object is either loaded or obtained from the cache with a read lock. The object's OID is always returned.
Parameters:
tx - The transaction context
oid - The identity of the object to load
object - The type of the object to load
timeout - The timeout waiting to acquire a lock on the object (specified in seconds)
Returns:
The object's OID
Throws:
ObjectNotFoundException - The object was not found in persistent storage
LockNotGrantedException - Timeout or deadlock occured attempting to acquire lock on object
PersistenceException - An error reported by the persistence engine
ClassNotPersistenceCapableException - The class is not persistent capable

load

public OID load(TransactionContext tx,
                OID oid,
                Object object,
                AccessMode suggestedAccessMode,
                int timeout,
                QueryResults results)
            throws ObjectNotFoundException,
                   LockNotGrantedException,
                   PersistenceException,
                   ClassNotPersistenceCapableException,
                   ObjectDeletedWaitingForLockException

markCreate

public void markCreate(TransactionContext tx,
                       OID oid,
                       Object object)
            throws PersistenceException,
                   LockNotGrantedException
Mark an object and its related or dependent object to be created
Parameters:
tx - The transaction context
oid - The identity of the object, or null
object - The newly created object

markDelete

public void markDelete(TransactionContext tx,
                       OID oid,
                       Object object,
                       int timeout)
            throws PersistenceException,
                   LockNotGrantedException

preStore

public OID preStore(TransactionContext tx,
                    OID oid,
                    Object object,
                    int timeout)
            throws LockNotGrantedException,
                   PersistenceException
Called at transaction commit to store an object that has been loaded during the transaction. If the object has been created in this transaction but without an identity, the object will be created in persistent storage. Otherwise the object will be stored and dirty checking might occur in order to determine whether the object is valid. The object's OID might change during this process, and the new OID will be returned. If the object was not stored (not modified), null is returned.
Parameters:
tx - The transaction context
oid - The object's identity
object - The object to store
timeout - The timeout waiting to acquire a lock on the object (specified in seconds)
Returns:
The object's OID if stored, null if ignored
Throws:
LockNotGrantedException - Timeout or deadlock occured attempting to acquire lock on object
PersistenceException - An error reported by the persistence engine

releaseLock

public void releaseLock(TransactionContext tx,
                        OID oid)
Called at transaction commit or rollback to release all locks held on the object. Must be called for all objects that were queried but not created within the transaction.
Parameters:
tx - The transaction context
oid - The object OID

revertObject

public void revertObject(TransactionContext tx,
                         OID oid,
                         Object object)
            throws PersistenceException
Reverts an object to the cached copy given the object's OID. The cached object is copied into the supplied object without affecting the locks, loading relations or emitting errors. This method is used during the rollback phase.
Parameters:
tx - The transaction context
oid - The object's oid
object - The object into which to copy
Throws:
PersistenceException - An error reported by the persistence engine obtaining a dependent object

softLock

public void softLock(TransactionContext tx,
                     OID oid,
                     int timeout)
            throws LockNotGrantedException
Acquire a write lock on the object in memory. A soft lock prevents other threads from changing the object, but does not acquire a lock on the database.
Parameters:
tx - The transaction context
oid - The object's OID
timeout - The timeout waiting to acquire a lock on the object (specified in seconds)
Throws:
LockNotGrantedException - Timeout or deadlock occured attempting to acquire lock on object persistent storage

store

public void store(TransactionContext tx,
                  OID oid,
                  Object object)
            throws LockNotGrantedException,
                   ObjectDeletedException,
                   ObjectModifiedException,
                   DuplicateIdentityException,
                   PersistenceException

update

public boolean update(TransactionContext tx,
                      OID oid,
                      Object object,
                      AccessMode suggestedAccessMode,
                      int timeout)
            throws ObjectNotFoundException,
                   LockNotGrantedException,
                   ObjectModifiedException,
                   PersistenceException,
                   ClassNotPersistenceCapableException,
                   ObjectDeletedWaitingForLockException
Updates an existing object to this engine. The object must not be persistent and must not have the identity of a persistent object. The object's OID is returned. The OID is guaranteed to be unique for this engine even if no identity was specified. If the object implements TimeStampable interface, verify the object's timestamp.
Parameters:
tx - The transaction context
oid - The object's identity
object - The object
timeout - The timeout waiting to acquire a lock on the object (specified in seconds)
Returns:
The object's OID
Throws:
ObjectNotFoundException - The object was not found in persistent storage
LockNotGrantedException - Timeout or deadlock occured attempting to acquire lock on object
PersistenceException - An error reported by the persistence engine
ClassNotPersistenceCapableException - The class is not persistent capable
ObjectModifiedException - Dirty checking mechanism may immediately report that the object was modified in the database during the long transaction.

updateCache

public void updateCache(TransactionContext tx,
                        OID oid,
                        Object object)
Update the cached object with changes done to its copy. The supplied object is copied into the cached object using a write lock. This method is generally called after a successful return from store(TransactionContext,OID,Object) and is assumed to have obtained a write lock.
Parameters:
tx - The transaction context
oid - The object's oid
object - The object to copy from

writeLock

public void writeLock(TransactionContext tx,
                      OID oid,
                      int timeout)
            throws ObjectDeletedException,
                   LockNotGrantedException,
                   PersistenceException
Acquire a write lock on the object. A write lock assures that the object exists and can be stored/deleted when the transaction commits. It prevents any concurrent updates to the object from this point on. However, it does not guarantee that the object has not been modified in the course of the transaction. For that the object must be loaded with exclusive access.
Parameters:
tx - The transaction context
oid - The object's OID
timeout - The timeout waiting to acquire a lock on the object (specified in seconds)
Throws:
LockNotGrantedException - Timeout or deadlock occured attempting to acquire lock on object
ObjectDeletedException - The object has been deleted from persistent storage
PersistenceException - An error reported by the persistence engine

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