org.exolab.castor.persist
public final class LockEngine extends 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: 6230 $ $Date: 2006-04-22 11:05:30 -0600 (Sat, 22 Apr 2006) $
Constructor Summary | |
---|---|
LockEngine(ConnectionFactory connectionFactory, ClassDescriptorResolver cdResolver, PersistenceFactory persistenceFactory)
Construct a new cache engine with the specified mapping table,
persistence engine and the log interceptor.
|
Method Summary | |
---|---|
void | closeCaches()
Close all caches (to allow for resource clean-up) |
OID | create(TransactionContext tx, OID oid, 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(Class cls)
Dump cached objects of specific type to output. |
boolean | expireCache(TransactionContext tx, OID oid, int timeout)
Expire object from the cache. |
void | expireCache(Class cls)
Forces the cache to be expired for the object represented by
ClassMolder and identity. |
void | expireCache()
Expires all objects of all types from cache. |
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 |
ClassMolder | getClassMolderByQuery(String name)
Returns the ClassMolder instance that has a named query associated with the name given. |
ClassMolder | getClassMolderWithDependent(Class cls) |
ConnectionFactory | getConnectionFactory() |
Persistence | getPersistence(Class cls) |
HashMap | getXATransactions()
Returns an association between Xid and transactions contexts.
|
boolean | isCached(Class cls, Object oid)
Provides information about whether an object of Class cls with identity iod is currently cached.
|
boolean | isLocked(Class cls, OID oid) |
OID | load(TransactionContext tx, OID oid, ProposedEntity proposedObject, AccessMode suggestedAccessMode, int timeout)
Loads an object of the specified type and identity from
persistent storage. |
OID | load(TransactionContext tx, OID oid, ProposedEntity proposedObject, 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. |
Parameters: persistenceFactory Factory for creating persistence engines for each object described in the map
Throws: MappingException Indicate that one of the mappings is invalid
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
Parameters: tx The transaction context oid The object's identity
Throws: PersistenceException An error reported by the persistence engine
Parameters: cls A class type.
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.
Parameters: cls Class type instance.
Parameters: tx The transaction context oid The object OID
Parameters: cls Class instance for whic a class molder should be returned.
Returns: The class molder for the specified class.
Parameters: name Name of a named query.
Returns: ClassMolder instance associated with the named query
Returns: Association between XId and transaction contexts.
Parameters: cls Class type. oid Object identity
Returns: True if the specified object is in the cache.
Parameters: tx The transaction context oid 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)
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 ObjectDeletedWaitingForLockException The object has been deleted, but is waiting for a lock.
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 LockNotGrantedException Timeout or deadlock occured attempting to acquire lock on object.
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
Parameters: tx The transaction context oid The object OID
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
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
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
Parameters: tx The transaction context oid The object's oid object The object to copy from
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