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.
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.
tx
- The transaction contextoid
- The identity of the object, or nullobject
- The newly created object
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)
tx
- The transaction contextoid
- The object's identityobject
- The object type
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.
tx
- The transaction contextoid
- 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.
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.
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)
- The object's OID if stored, null if ignored
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.
tx
- The transaction contextoid
- 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.
tx
- The transaction contextoid
- The object's oidobject
- The object into which to copy
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.
tx
- The transaction contextoid
- The object's OIDtimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
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.
tx
- The transaction contextoid
- The object's identityobject
- The objecttimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)
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.
tx
- The transaction contextoid
- The object's oidobject
- 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.
tx
- The transaction contextoid
- The object's OIDtimeout
- The timeout waiting to acquire a lock on the
object (specified in seconds)