addTxSynchronizable
public void addTxSynchronizable(TxSynchronizable synchronizable)
Register a listener which wants to synchronize its state to the state of the
transaction.
synchronizable
- The TxSynchronizable implementation to register.
close
public void close()
throws TransactionAbortedException
Closes all Connections. Must be called before the end of the transaction
in EJB environment or after commit in standalone case. Throws an
IllegalStateException if this method has been called after the end of the
transaction.
TransactionAbortedException
- The transaction has been aborted due to
inconsistency, duplicate object identity, error with the persistence
engine or any other reason.
commit
public void commit()
throws TransactionAbortedException
Commits all changes and closes the transaction releasing all locks on all
objects. All objects are now transient. Must be called after a call to
prepare()
has returned successfully. Throws an IllegalStateException
when called without calling
prepare()
first.
TransactionAbortedException
- The transaction has been aborted due to
inconsistency, duplicate object identity, error with the persistence
engine or any other reason.
create
public void create(ClassMolder molder,
Object object,
OID depended)
throws PersistenceException
Creates a new object in persistent storage. The object will be persisted
only if the transaction commits. If an identity is provided then duplicate
identity check happens in this method, if no identity is provided then
duplicate identity check occurs when the transaction completes and the
object is not visible in this transaction.
molder
- The molder of the creating class.object
- The object to persist.depended
- The master object's OID if exist.
PersistenceException
- An object with this identity already exists in
persistent storage. The class is not persistent capable. An error
reported by the persistence engine.
delete
public void delete(Object object)
throws PersistenceException
Deletes the object from persistent storage. The deletion will take effect
only if the transaction is committed, but the object is no longer viewable
for the current transaction and locks for access from other transactions
will block until this transaction completes. A write lock is acquired in
order to assure the object can be deleted.
object
- The object to delete from persistent storage.
PersistenceException
- The object has not been queried or created in this
transaction. Timeout or deadlock occured attempting to acquire lock on
object. An error reported by the persistence engine.
expireCache
public void expireCache(ClassMolder molder,
Identity identity)
throws PersistenceException
Expire object from the cache. Objects expired from the cache will be
read from persistent storage, as opposed to being read from the
cache, during subsequent load/query operations.
molder
- The class persistence molder.identity
- The object's identity.
PersistenceException
- If identity is null or any problem that happens
during expiration of cache values.
getClassLoader
public ClassLoader getClassLoader()
Get the current application ClassLoader.
- the current ClassLoader's instance.
null
if none
has been provided
getConnection
public Connection getConnection(LockEngine engine)
throws PersistenceException
Return an open connection for the specified engine. Only one connection should
be created for a given engine in the same transaction.
engine
- The persistence engine.
getConnectionInfo
public DbMetaInfo getConnectionInfo(LockEngine engine)
throws PersistenceException
Returns meta-data related to the RDBMS used.
engine
- LockEngine instance used.
- A DbMetaInfo instance describing various features of the underlying
RDBMS.
getDatabase
public Database getDatabase()
getLockTimeout
public int getLockTimeout()
Returns the timeout waiting to acquire a lock. The timeout is specified in
seconds.
- The timeout waiting to acquire a lock in seconds.
getNamedQuery
public String getNamedQuery(ClassMolder molder,
String name)
throws QueryException
Creates an OQL query based upon a named query as defined in the
mapping file.
molder
- Specific class molder.name
- Name of the (named) query to create.
getStatus
public int getStatus()
Returns the status of this transaction.
- The status of this transaction.
getTransactionTimeout
public int getTransactionTimeout()
Returns the timeout of this transaction. The timeout is specified in seconds.
- The timeout of this transaction in seconds.
getWaitOnLock
public ObjectLock getWaitOnLock()
Returns the lock which this transaction attempts to acquire.
- The lock which this transaction attempts to acquire
isAutoStore
public boolean isAutoStore()
Test if autoStore option is enabled or not.
true
if autoStore option is enabled.
isCreated
public boolean isCreated(Object object)
Returns true if the object is marked as created in this transaction. Note
that this does not find objects in the 'transitional' state of creating.
Primarily intended to be used by tests.
object
- The object to test the state of in this transaction.
true
if the object is marked as created within this
transaction.
isDeleted
public boolean isDeleted(Object object)
Returns true if and only if the specified object is loaded or created in this
transaction and is deleted.
object
- The object to test the state of in this transaction.
true
if the object is deleted.
isDeletedByOID
public boolean isDeletedByOID(OID oid)
isDepended
public boolean isDepended(OID master,
Object dependent)
isLocked
public boolean isLocked(Class cls,
Identity identity,
LockEngine lockEngine)
Returns true if the object given is locked.
cls
- Class instance of the object to be investigated.identity
- Identity of the object to be investigated.lockEngine
- Current LcokEngine instance
- True if the object in question is locked.
isOpen
public boolean isOpen()
Returns true if the transaction is open.
true
if the transaction is open.
isPersistent
public boolean isPersistent(Object object)
Returns true if the object is persistent in this transaction.
true
if persistent in transaction.
isReadOnly
public boolean isReadOnly(Object object)
Check to see whether this transaction considers an object to have been marked
read-only.
object
- The object to test for read-only status
true
if the object is marked read-only in this transaction;
otherwise, false
.
isRecorded
public boolean isRecorded(Object object)
Returns true if the object is previously queried/loaded/update/create in
this transaction.
true
if recorded in this transaction.
isUpdateCacheNeeded
public boolean isUpdateCacheNeeded(Object object)
Retrieves the state of the object in this transaction. Specifically, in
this case, that the object requires a cache update.
object
- The object to test the state of in this transaction.
true
if the object is recorded in this transaction with
the requested state.
isUpdatePersistNeeded
public boolean isUpdatePersistNeeded(Object object)
Retrieves the state of the object in this transaction. Specifically, in
this case, that the object requires a persistence update.
object
- The object to test the state of in this transaction.
true
if the object is recorded in this transaction with
the requested state.
iterateReadWriteObjectsInTransaction
public Iterator iterateReadWriteObjectsInTransaction()
Expose an enumeration of the commited object entries to allow TxSynchronizable
to iterate through the objects.
- Iterator of modifiable (read-write) object entries.
load
public Object load(Identity identity,
ProposedEntity proposedObject,
AccessMode suggestedAccessMode)
throws PersistenceException
Load an object for use within the transaction. Multiple access to the same
object within the transaction will return the same object instance (except
for read-only access).
This method is similar to
fetch(ClassMolder,Identity,AccessMode)
except that it will load the object
only once within a transaction and always return the same instance.
If the object is loaded for read-only then no lock is acquired and updates
to the object are not reflected at commit time. If the object is loaded for
read-write then a read lock is acquired (unless timeout or deadlock detected)
and the object is stored at commit time. The object is then considered
persistent and may be deleted or upgraded to write lock. If the object is
loaded for exclusive access then a write lock is acquired and the object is
synchronized with the persistent copy.
Attempting to load the object twice in the same transaction, once with
exclusive lock and once with read-write lock will result in an exception.
identity
- The object's identity.proposedObject
- The object to fetch (single instance per transaction).suggestedAccessMode
- The access mode (see AccessMode
) the values
in persistent storage.
PersistenceException
- Timeout or deadlock occured attempting to acquire
lock on object. The object was not found in persistent storage. An error
reported by the persistence engine.
load
public Object load(Identity identity,
ProposedEntity proposedObject,
AccessMode suggestedAccessMode,
QueryResults results)
throws PersistenceException
Load an object for use within the transaction. Multiple access to the same
object within the transaction will return the same object instance (except
for read-only access).
In addition to
load(Identity,ProposedEntity,AccessMode)
a QueryResults can be specified.
identity
- The object's identity.proposedObject
- The object to fetch (single instance per transaction).suggestedAccessMode
- The access mode (see AccessMode
) the values
in persistent storage.results
- The QueryResult that the data to be loaded from.
PersistenceException
- Timeout or deadlock occured attempting to acquire
lock on object. The object was not found in persistent storage. An error
reported by the persistence engine.
markCreate
public void markCreate(ClassMolder molder,
Object object,
OID rootObjectOID)
throws PersistenceException
Walk a data object tree starting from the specified object, and mark all
objects to be created.
molder
- The class persistence molder.object
- The object to persist.rootObjectOID
- The OID of the root object to start walking.
PersistenceException
- An object with this identity already exists in
persistent storage. The class is not persistent capable. An error
reported by the persistence engine.
markModified
public void markModified(Object object,
boolean updatePersist,
boolean updateCache)
markUpdate
public boolean markUpdate(ClassMolder molder,
Object object,
OID depended)
throws PersistenceException
Update a new object in persistent storage and returns the object's OID. The
object will be persisted only if the transaction commits. If an identity is
provided then duplicate identity check happens in this method, if no identity
is provided then duplicate identity check occurs when the transaction
completes and the object is not visible in this transaction.
Update will also mark objects to be created if the TIMESTAMP equals to
NO_TIMESTAMP.
molder
- The object's molder.object
- The object to persist.depended
- The master objects of the specified object to be created if
exisit.
- true if the object is marked to be created.
PersistenceException
- An object with this identity already exists in
persistent storage. The class is not persistent capable. Dirty checking
mechanism may immediately report that the object was modified in the
database during the long transaction. An error reported by the
persistence engine.
prepare
public boolean prepare()
throws TransactionAbortedException
Prepares the transaction prior to committing it. Indicates whether the
transaction is read-only (i.e. no modified objects), can commit, or an error
has occured and the transaction must be rolled back. This method performs
actual storage into the persistence storage. Multiple calls to this method
can be done, and do not release locks, allowing checkpoint to occur.
An IllegalStateException is thrown if transaction is not in the proper state
to perform this operation.
- True if the transaction can commit, false if the transaction is
read only
TransactionAbortedException
- The transaction has been aborted due to
inconsistency, duplicate object identity, error with the persistence
engine or any other reason.
query
public QueryResults query(LockEngine engine,
PersistenceQuery query,
AccessMode accessMode,
boolean scrollable)
throws PersistenceException
Perform a query using the query mechanism with the specified access mode. The
query is performed in this transaction, and the returned query results can
only be used while this transaction is open. It is assumed that the query
mechanism is compatible with the persistence engine.
engine
- The persistence engine.query
- A query against the persistence engine.accessMode
- The access mode.scrollable
- The db cursor mode.
removeTxSynchronizable
public void removeTxSynchronizable(TxSynchronizable synchronizable)
Unregister a listener which wants to synchronize its state to the state of the
transaction.
synchronizable
- The TxSynchronizable implementation to unregister.
rollback
public void rollback()
Rolls back all changes and closes the transaction releasing all locks on
all objects. All objects are now transient, if they were queried in this
transaction. This method may be called at any point during the transaction.
Throws an IllegalStateException if transaction is not in the proper state
to perform this operation.
setAutoStore
public void setAutoStore(boolean autoStore)
Enable or disable autoStore. If enabled, all new objects, which are reachable
from other object that are queried, loaded, created in the transaction, will be
created when the transaction is committed.
autoStore
- When set to true
autoStore will be enabled.
setCallback
public void setCallback(CallbackInterceptor callback)
Overrides the default callback interceptor by a custom interceptor for this
database source.
The interceptor is a callback that notifies data objects on persistent state
events.
If callback interceptor is not overriden, events will be sent to data object
that implements the org.exolab.castor.jdo.Persistent interface.
callback
- The callback interceptor, disabled if null.
setInstanceFactory
public void setInstanceFactory(InstanceFactory factory)
Overrides the default instance factory by a custom one for this database
source.
The factory is used to obatain a new instance of data object when it is
needed during loading.
factory
- The instanceFactory to be used, disable if null.
setLockTimeout
public void setLockTimeout(int timeout)
Sets the timeout waiting to acquire a lock. The timeout is specified in
seconds.
timeout
- The timeout waiting to acquire a lock in seconds.
setStatus
public void setStatus(int status)
Sets the status of the current transaction to the given one.
status
- The status to set for this transaction.
setTransactionTimeout
public void setTransactionTimeout(int timeout)
Sets the timeout of this transaction. The timeout is specified in seconds.
timeout
- The timeout for this transaction in seconds.
setWaitOnLock
public void setWaitOnLock(ObjectLock lock)
Indicates which lock this transaction is waiting for. When a transaction
attempts to acquire a lock it must indicate which lock it attempts to
acquire in order to perform dead-lock detection. This method is called by
ObjectLock
before entering the temporary lock-acquire state.
lock
- The lock which this transaction attempts to acquire
update
public void update(ClassMolder molder,
Object object,
OID depended)
throws PersistenceException
Update a new object in persistent storage and returns the object's OID. The
object will be persisted only if the transaction commits. If an identity is
provided then duplicate identity check happens in this method, if no identity
is provided then duplicate identity check occurs when the transaction
completes and the object is not visible in this transaction.
Update will also mark objects to be created if the TIMESTAMP equals to
NO_TIMESTAMP.
molder
- The object's molder.object
- The object to persist.depended
- The master objects of the specified object to be created if
exisit.
PersistenceException
- An object with this identity already exists in
persistent storage. The class is not persistent capable. Dirty checking
mechanism may immediately report that the object was modified in the
database during the long transaction. An error reported by the persistence
engine.
writeLock
public void writeLock(Object object,
int timeout)
throws PersistenceException
Acquire a write lock on the object. Read locks are implicitly available
when the object is queried. A write lock is only granted for objects that
are created or deleted or for objects loaded in exclusive mode - this
method can obtain such a lock explicitly. If the object already has a
write lock in this transaction or a read lock in this transaction but no
read lock in any other transaction, a write lock is obtained. If this
object has a read lock in any other transaction this method will block
until the other transaction will release its lock. If the specified
timeout has elapsed or a deadlock has been detected, an exception will be
thrown but the current lock will be retained.
object
- The object to lock.timeout
- Timeout waiting to acquire lock, specified in seconds, zero
for no waiting, negative to use the default timeout for this transaction.
PersistenceException
- The object has not been queried or created in this
transaction. Timeout or deadlock occured attempting to acquire lock on
object. An error reported by the persistence engine.