|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.exolab.castor.persist.LockEngine
public final class LockEngine
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.
Constructor Summary | |
---|---|
LockEngine(ConnectionFactory connectionFactory,
MappingResolver mapResolver,
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,
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 Dependent class will not be returned to avoid persistenting a dependent class without |
ClassMolder |
getClassMolderWithDependent(java.lang.Class cls)
|
ConnectionFactory |
getConnectionFactory()
|
Persistence |
getPersistence(java.lang.Class cls)
|
java.util.HashMap |
getXATransactions()
Returns an association between Xid and transactions contexts. |
boolean |
isCached(java.lang.Class cls,
java.lang.Object oid)
Provides information about whether an object of Class cls with identity iod is currently cached. |
OID |
load(TransactionContext tx,
OID oid,
ProposedObject proposedObject,
AccessMode suggestedAccessMode,
int timeout)
Loads an object of the specified type and identity from persistent storage. |
OID |
load(TransactionContext tx,
OID oid,
ProposedObject proposedObject,
AccessMode suggestedAccessMode,
int timeout,
QueryResults results)
|
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 |
---|
public LockEngine(ConnectionFactory connectionFactory, MappingResolver mapResolver, PersistenceFactory persistenceFactory) throws MappingException
dbName
- Name of database configuration.mapResolver
- Provides mapping information for objects
supported by this cachepersistenceFactory
- Factory for creating persistence engines for each
object described in the map
MappingException
- Indicate that one of the mappings is invalidMethod Detail |
---|
public ConnectionFactory getConnectionFactory()
public ClassMolder getClassMolder(java.lang.Class cls)
cls
- Class instance for whic a class molder should be returned.
public ClassMolder getClassMolderWithDependent(java.lang.Class cls)
public Persistence getPersistence(java.lang.Class cls)
public OID load(TransactionContext tx, OID oid, ProposedObject proposedObject, AccessMode suggestedAccessMode, int timeout) throws ObjectNotFoundException, LockNotGrantedException, PersistenceException, ClassNotPersistenceCapableException, ObjectDeletedWaitingForLockException
tx
- The transaction contextoid
- The identity of the object to loadobject
- The type of the object to loadsuggestedAccessMode
- The desired access modetimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
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.public OID load(TransactionContext tx, OID oid, ProposedObject proposedObject, AccessMode suggestedAccessMode, int timeout, QueryResults results) throws ObjectNotFoundException, LockNotGrantedException, PersistenceException, ClassNotPersistenceCapableException, ObjectDeletedWaitingForLockException
ObjectNotFoundException
LockNotGrantedException
PersistenceException
ClassNotPersistenceCapableException
ObjectDeletedWaitingForLockException
public void markCreate(TransactionContext tx, OID oid, java.lang.Object object) throws PersistenceException, LockNotGrantedException
tx
- The transaction contextoid
- The identity of the object, or nullobject
- The newly created object
PersistenceException
- An error reported by the persistence engine
LockNotGrantedException
- Timeout or deadlock occured attempting to acquire lock on object.public OID create(TransactionContext tx, OID oid, java.lang.Object object) throws DuplicateIdentityException, PersistenceException, ClassNotPersistenceCapableException
tx
- The transaction contextoid
- The identity of the object, or nullobject
- The newly created object
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 capablepublic void delete(TransactionContext tx, OID oid) throws PersistenceException
forgetObject(org.castor.persist.TransactionContext, org.exolab.castor.persist.OID)
tx
- The transaction contextoid
- The object's identity
PersistenceException
- An error reported by the
persistence enginepublic void markDelete(TransactionContext tx, OID oid, java.lang.Object object, int timeout) throws PersistenceException, LockNotGrantedException
PersistenceException
LockNotGrantedException
public boolean update(TransactionContext tx, OID oid, java.lang.Object object, AccessMode suggestedAccessMode, int timeout) throws ObjectNotFoundException, LockNotGrantedException, ObjectModifiedException, PersistenceException, ClassNotPersistenceCapableException, ObjectDeletedWaitingForLockException
tx
- The transaction contextoid
- The object's identityobject
- The objectsuggestedAccessMode
- The desired access modetimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
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
public OID preStore(TransactionContext tx, OID oid, java.lang.Object object, int timeout) throws LockNotGrantedException, PersistenceException
tx
- The transaction contextoid
- The object's identityobject
- The object to storetimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
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 enginepublic void store(TransactionContext tx, OID oid, java.lang.Object object) throws LockNotGrantedException, ObjectDeletedException, ObjectModifiedException, DuplicateIdentityException, PersistenceException
LockNotGrantedException
ObjectDeletedException
ObjectModifiedException
DuplicateIdentityException
PersistenceException
public void writeLock(TransactionContext tx, OID oid, int timeout) throws ObjectDeletedException, LockNotGrantedException, PersistenceException
tx
- The transaction contextoid
- The object's OIDtimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
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 enginepublic void softLock(TransactionContext tx, OID oid, int timeout) throws LockNotGrantedException
tx
- The transaction contextoid
- The object's OIDtimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
LockNotGrantedException
- Timeout or deadlock occured
attempting to acquire lock on object
persistent storagepublic void revertObject(TransactionContext tx, OID oid, java.lang.Object object) throws PersistenceException
tx
- The transaction contextoid
- The object's oidobject
- The object into which to copy
PersistenceException
- An error reported by the
persistence engine obtaining a dependent objectpublic void updateCache(TransactionContext tx, OID oid, java.lang.Object object)
store(org.castor.persist.TransactionContext, org.exolab.castor.persist.OID, java.lang.Object)
and is assumed to have obtained a write
lock.
tx
- The transaction contextoid
- The object's oidobject
- The object to copy frompublic void releaseLock(TransactionContext tx, OID oid)
tx
- The transaction contextoid
- The object OIDpublic void forgetObject(TransactionContext tx, OID oid)
tx
- The transaction contextoid
- The object OIDpublic boolean expireCache(TransactionContext tx, OID oid, int timeout) throws ClassNotPersistenceCapableException, LockNotGrantedException, ObjectDeletedException, PersistenceException
tx
- The transaction contextoid
- The object OIDtimeout
- The max time to wait while acquiring a lock on the
object (specified in seconds)
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.public void expireCache(java.lang.Class cls)
cls
- Class type instance.public void expireCache()
public void dumpCache()
public void closeCaches()
public void dumpCache(java.lang.Class cls)
cls
- A class type.public java.util.HashMap getXATransactions()
public boolean isCached(java.lang.Class cls, java.lang.Object oid)
cls
- Class type.oid
- Object identity
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |