LockEngine (Castor JavaDoc)

java.lang.Object
- org.exolab.castor.persist.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 Cache 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.
IMPLEMENTATION NOTES:
An object may be persistent in multiple caches at any given time. There is no way to load an object from multiple caches, but an object can be loaded in one engine and then made persistent in another. The engines are totally independent and no conflicts should occur.
Each class hierarchy gets its own cache, so caches can be controlled on a class-by-class basis.

Version:

$Revision: 8699 $ $Date: 2006-04-22 11:05:30 -0600 (Sat, 22 Apr 2006) $

Author:

Assaf Arkin, Thomas Yip, Bruce Snyder

Constructor Summary

Constructors
Constructor	Description
`LockEngine(DatabaseContext databaseContext, ClassDescriptorResolver cdResolver, PersistenceFactory persistenceFactory)`	Construct a new cache engine with the specified mapping table, persistence engine and the log interceptor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`closeCaches()`	Close all caches (to allow for resource clean-up).
`OID`	`create(TransactionContext tx, OID oid, java.lang.Object object)`	Creates a new object in the persistence storage.
`void`	`delete(TransactionContext tx, OID oid)`	Called at transaction commit time to delete the object.
`void`	`dumpCache()`	Dump cached objects of all types to output.
`void`	`dumpCache(java.lang.Class cls)`	Dump cached objects of specific type to output.
`void`	`expireCache()`	Expires all objects of all types from cache.
`void`	`expireCache(java.lang.Class cls)`	Forces the cache to be expired for the object represented by ClassMolder and identity.
`boolean`	`expireCache(TransactionContext tx, OID oid, int timeout)`	Expire object from the cache.
`void`	`forgetObject(TransactionContext tx, OID oid)`	Called at transaction commit or rollback to forget an object and release its locks.
`ClassMolder`	`getClassMolder(java.lang.Class cls)`	Get classMolder which represents the given java data object class.
`ClassMolder`	`getClassMolder(java.lang.String classname)`
`ClassMolder`	`getClassMolderByNativeQuery(java.lang.String name)`	Returns the ClassMolder instance that has a named native query associated with the name given.
`ClassMolder`	`getClassMolderByQuery(java.lang.String name)`	Returns the ClassMolder instance that has a named query associated with the name given.
`ClassMolder`	`getClassMolderWithDependent(java.lang.Class cls)`
`ClassMolder`	`getClassMolderWithDependent(java.lang.String classname)`
`DatabaseContext`	`getDatabaseContext()`
`Persistence`	`getPersistence(java.lang.Class cls)`
`java.util.HashMap<javax.transaction.xa.Xid,TransactionContext>`	`getXATransactions()`	Returns an association between Xid and transactions contexts.
`boolean`	`isCached(java.lang.Class cls, OID oid)`	Provides information about whether an object of Class cls with identity iod is currently cached.
`boolean`	`isLocked(java.lang.Class cls, OID oid)`
`void`	`load(AbstractTransactionContext tx, OID paramoid, ProposedEntity proposedObject, AccessMode suggestedAccessMode, int timeout, QueryResults results, ClassMolder paramMolder, Identity identity)`	Loads an object of the specified type and identity from persistent storage.
`void`	`markCreate(TransactionContext tx, OID oid, java.lang.Object object)`	Mark an object and its related or dependent object to be created.
`void`	`markDelete(TransactionContext tx, OID oid, java.lang.Object object, int timeout)`
`OID`	`preStore(TransactionContext tx, OID oid, java.lang.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, java.lang.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, java.lang.Object object)`
`boolean`	`update(TransactionContext tx, OID oid, java.lang.Object object, AccessMode suggestedAccessMode, int timeout)`	Updates an existing object to this engine.
`void`	`updateCache(TransactionContext tx, OID oid, java.lang.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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LockEngine
```
public LockEngine(DatabaseContext databaseContext,
                  ClassDescriptorResolver cdResolver,
                  PersistenceFactory persistenceFactory)
           throws MappingException
```
    Construct a new cache engine with the specified mapping table, persistence engine and the log interceptor.
    
    Parameters:
    
    databaseContext -
    
    cdResolver -
    
    persistenceFactory - Factory for creating persistence engines for each object described in the map.
    
    Throws:
    
    MappingException - Indicate that one of the mappings is invalid
- Method Detail
  - getDatabaseContext
```
public DatabaseContext getDatabaseContext()
```
  - getClassMolder
```
public ClassMolder getClassMolder(java.lang.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.
    
    Parameters:
    
    cls - Class instance for whic a class molder should be returned.
    
    Returns:
    
    The class molder for the specified class.
  - getClassMolder
```
public ClassMolder getClassMolder(java.lang.String classname)
```
  - getClassMolderWithDependent
```
public ClassMolder getClassMolderWithDependent(java.lang.Class cls)
```
  - getClassMolderWithDependent
```
public ClassMolder getClassMolderWithDependent(java.lang.String classname)
```
  - getClassMolderByQuery
```
public ClassMolder getClassMolderByQuery(java.lang.String name)
```
    Returns the ClassMolder instance that has a named query associated with the name given.
    
    Parameters:
    
    name - Name of a named query.
    
    Returns:
    
    ClassMolder instance associated with the named query.
  - getClassMolderByNativeQuery
```
public ClassMolder getClassMolderByNativeQuery(java.lang.String name)
```
    Returns the ClassMolder instance that has a named native query associated with the name given.
    
    Parameters:
    
    name - Name of a named query.
    
    Returns:
    
    ClassMolder instance associated with the named native query.
  - getPersistence
```
public Persistence getPersistence(java.lang.Class cls)
```
  - load
```
public void load(AbstractTransactionContext tx,
                 OID paramoid,
                 ProposedEntity proposedObject,
                 AccessMode suggestedAccessMode,
                 int timeout,
                 QueryResults results,
                 ClassMolder paramMolder,
                 Identity identity)
          throws PersistenceException,
                 java.lang.InstantiationException,
                 java.lang.IllegalAccessException,
                 java.lang.ClassNotFoundException
```
    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
    
    paramoid - The identity of the object to load
    
    proposedObject - The type of the object to load
    
    suggestedAccessMode - The desired access mode
    
    timeout - The timeout waiting to acquire a lock on the object (specified in seconds)
    
    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
    
    ObjectDeletedWaitingForLockException - The object has been deleted, but is waiting for a lock.
    
    java.lang.InstantiationException
    
    java.lang.IllegalAccessException
    
    java.lang.ClassNotFoundException
  - markCreate
```
public void markCreate(TransactionContext tx,
                       OID oid,
                       java.lang.Object object)
                throws PersistenceException
```
    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.
    
    Throws:
    
    PersistenceException - An error reported by the persistence engine. Timeout or deadlock occured attempting to acquire lock on object.
  - create
```
public OID create(TransactionContext tx,
                  OID oid,
                  java.lang.Object object)
           throws PersistenceException
```
    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)
            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(org.castor.persist.TransactionContext, org.exolab.castor.persist.OID)
    Parameters:
    
    tx - The transaction context
    
    oid - The object's identity
    
    Throws:
    
    PersistenceException - An error reported by the persistence engine
  - markDelete
```
public void markDelete(TransactionContext tx,
                       OID oid,
                       java.lang.Object object,
                       int timeout)
                throws PersistenceException
```
    Throws:
    
    PersistenceException
  - update
```
public boolean update(TransactionContext tx,
                      OID oid,
                      java.lang.Object object,
                      AccessMode suggestedAccessMode,
                      int timeout)
               throws PersistenceException
```
    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
    
    suggestedAccessMode - The desired access mode
    
    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.
    
    ObjectDeletedWaitingForLockException
  - preStore
```
public OID preStore(TransactionContext tx,
                    OID oid,
                    java.lang.Object object,
                    int timeout)
             throws 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
    
    ObjectDeletedException - The object has been deleted from persistent storage
    
    ObjectModifiedException - The object has been modified in persistent storage since it was loaded, the memory image is no longer valid
    
    DuplicateIdentityException - An object with this identity already exists in persistent storage
    
    PersistenceException - An error reported by the persistence engine
  - store
```
public void store(TransactionContext tx,
                  OID oid,
                  java.lang.Object object)
           throws PersistenceException
```
    Throws:
    
    PersistenceException
  - writeLock
```
public void writeLock(TransactionContext tx,
                      OID oid,
                      int timeout)
               throws 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
  - 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
  - revertObject
```
public void revertObject(TransactionContext tx,
                         OID oid,
                         java.lang.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
  - updateCache
```
public void updateCache(TransactionContext tx,
                        OID oid,
                        java.lang.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(org.castor.persist.TransactionContext, org.exolab.castor.persist.OID, java.lang.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
  - 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
  - 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
  - expireCache
```
public boolean expireCache(TransactionContext tx,
                           OID oid,
                           int timeout)
                    throws PersistenceException
```
    Expire object from the cache. If the object to be expired is currently cached, then a write lock is first acquired for this object. In addition, a write lock is acquired on all objects related to, or contained within, this object. The version of the objects represented by their locks is then marked as "expired". Upon the release of each write lock (@see TransactionContext#expireCache), the cached version of the objects will not be placed back in the cache (@see TypeInfo#release). A subsequent read/query transaction will therefore load the values of the object from persistent storage.
    
    Parameters:
    
    tx - The transaction context
    
    oid - The object OID
    
    timeout - The max time to wait while acquiring a lock on the object (specified in seconds)
    
    Returns:
    
    True if the object was expired successfully from the cache.
    
    Throws:
    
    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.
    
    ObjectDeletedException - Object has been deleted from the persistence store.
  - expireCache
```
public void expireCache(java.lang.Class cls)
```
    Forces the cache to be expired for the object represented by ClassMolder and identity. If identity is null then expire all objects of the type represented by ClassMolder.
    
    Parameters:
    
    cls - Class type instance.
  - expireCache
```
public void expireCache()
```
    Expires all objects of all types from cache.
  - dumpCache
```
public void dumpCache()
```
    Dump cached objects of all types to output.
  - closeCaches
```
public void closeCaches()
```
    Close all caches (to allow for resource clean-up).
  - dumpCache
```
public void dumpCache(java.lang.Class cls)
```
    Dump cached objects of specific type to output.
    
    Parameters:
    
    cls - A class type.
  - getXATransactions
```
public java.util.HashMap<javax.transaction.xa.Xid,TransactionContext> 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.
    
    Returns:
    
    Association between XId and transaction contexts.
  - isCached
```
public boolean isCached(java.lang.Class cls,
                        OID oid)
```
    Provides information about whether an object of Class cls with identity iod is currently cached.
    
    Parameters:
    
    cls - Class type.
    
    oid - Object identity
    
    Returns:
    
    True if the specified object is in the cache.
  - isLocked
```
public boolean isLocked(java.lang.Class cls,
                        OID oid)
```

Class LockEngine

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LockEngine

Method Detail

getDatabaseContext

getClassMolder

getClassMolder

getClassMolderWithDependent

getClassMolderWithDependent

getClassMolderByQuery

getClassMolderByNativeQuery

getPersistence

load

markCreate

create

delete

markDelete

update

preStore

store

writeLock

softLock

revertObject

updateCache

releaseLock

forgetObject

expireCache

expireCache

expireCache

dumpCache

closeCaches

dumpCache

getXATransactions

isCached

isLocked