org.exolab.castor.persist
public abstract class TransactionContext extends Object
Version: $Revision: 1.2 $ $Date: 2003/03/03 17:18:29 $
Nested Class Summary | |
---|---|
static class | TransactionContext.ObjectEntry
A transaction records all objects accessed during the lifetime
of the transaction in this record (queries and created). |
Field Summary | |
---|---|
static int | OBJECT_STATE_HOLLOW |
static int | OBJECT_STATE_PERSISTENT |
static int | OBJECT_STATE_PERSISTENT_DELETED |
static int | OBJECT_STATE_PERSISTENT_NEW |
static int | OBJECT_STATE_PERSISTENT_NEW_DELETED |
static int | OBJECT_STATE_READ_ONLY |
static int | OBJECT_STATE_TRANSIENT
IMPLEMENTATION NOTES:
An object is considered persistent only if it was queried or created
within the context of this transaction. |
Constructor Summary | |
---|---|
TransactionContext(Database db)
Create a new transaction context. | |
TransactionContext(Database db, Xid xid)
Create a new transaction context. |
Method Summary | |
---|---|
TransactionContext.ObjectEntry | addObjectEntry(OID oid, Object object)
Adds a new entry recording the use of the object in this
transaction. |
void | addTxSynchronizable(TxSynchronizable synchronizable)
Register a listener which wants to synchronize its state
to the state of the transaction. |
void | close()
Closes all Connections.
|
protected abstract void | closeConnections()
The derived class must implement this method and close all the
connections used in this transaction. |
void | commit()
Commits all changes and closes the transaction releasing all
locks on all objects. |
protected abstract void | commitConnections()
The derived class must implement this method and commit all the
connections used in this transaction. |
void | create(LockEngine engine, ClassMolder molder, Object object, OID depended)
Creates a new object in persistent storage. |
void | delete(Object object)
Deletes the object from persistent storage. |
Object | fetch(LockEngine engine, ClassMolder molder, Object identity, AccessMode suggestedAccessMode) |
ClassLoader | getClassLoader()
Get the current application ClassLoader.
|
abstract Object | getConnection(LockEngine engine)
The derived class must implement this method and return an open
connection for the specified engine. |
Database | getDatabase() |
Object | getIdentity(Object object)
Returns the object's identity. |
int | getLockTimeout()
Returns the timeout waiting to acquire a lock. |
TransactionContext.ObjectEntry | getObjectEntry(LockEngine engine, OID oid)
Retrieves the object entry for the specified object.
|
TransactionContext.ObjectEntry | getObjectEntry(Object object)
Returns the entry for the object from the object. |
int | getObjectState(Object object) |
TransactionContext.ObjectEntry | getReadOnlyObjectEntry(OID oid) |
PersistenceInfoGroup | getScope() |
int | getStatus()
Returns the status of this transaction. |
int | getTransactionTimeout()
Returns the timeout of this transaction. |
ObjectLock | getWaitOnLock()
Returns the lock which this transaction attempts to acquire.
|
protected Xid | getXid() |
boolean | isAutoStore()
Test if autoStore options is enabled or not. |
boolean | isDeleted(Object object)
True if and only if the specified object is loaded or created
in this transaction and is deleted. |
boolean | isDeletedByOID(OID oid) |
boolean | isDepended(OID master, Object dependent) |
boolean | isOpen()
Returns true if the transaction is open. |
boolean | isPersistent(Object object)
Returns true if the object is persistent in this transaction.
|
boolean | isReadOnly(Object object) |
boolean | isRecorded(Object object)
Returns true if the object is previously queried/loaded/update/create
in this transaction |
Object | load(LockEngine engine, ClassMolder molder, Object identity, Object objectToBeLoaded, AccessMode suggestedAccessMode)
Load an object for use within the transaction. |
Object | load(LockEngine engine, ClassMolder molder, Object identity, Object objectToBeLoaded, AccessMode suggestedAccessMode, QueryResults results)
Load an object for use within the transaction. |
void | makeReadOnly(Object object)
Makes the object read-only: move it to the hashtable of readonly objects
The object must be already in the transaction.
|
void | markCreate(LockEngine engine, ClassMolder molder, Object object, OID depended)
Walk a data object tree starting from the specified object, and
mark all object to be created.
|
void | markDelete(LockEngine engine, Class type, Object identity)
Marks an object for deletion. |
void | markModified(Object object, boolean updatePersist, boolean updateCache) |
boolean | markUpdate(LockEngine engine, ClassMolder molder, Object object, OID depended)
Update a new object in persistent storage and returns the
object's OID. |
boolean | prepare()
Prepares the transaction prior to committing it. |
QueryResults | query(LockEngine engine, PersistenceQuery query, AccessMode accessMode, boolean scrollable)
Perform a query using the query mechanism and in the specified
access mode. |
QueryResults | query(LockEngine engine, PersistenceQuery query, AccessMode accessMode) |
TransactionContext.ObjectEntry | rehash(Object object, OID oid) |
void | release(Object object)
Releases the lock granted on the object. |
TransactionContext.ObjectEntry | removeObjectEntry(Object object)
Removes the entry for an object and returns it. |
void | removeTxSynchronizable(TxSynchronizable synchronizable) |
void | rollback() |
protected abstract void | rollbackConnections()
The derived class must implement this method and rollback all
the connections used in this transaction. |
void | setAutoStore(boolean autoStore)
Enable or disable autoStore.
|
void | setCallback(CallbackInterceptor callback)
Overrides the default callback interceptor by a custom
interceptor for this database source.
|
void | setInstanceFactory(InstanceFactory factory)
Overrides the default instance factory by a custom one for
this database source.
|
void | setLockTimeout(int timeout)
Sets the timeout waiting to acquire a lock. |
void | setTransactionTimeout(int timeout)
Sets the timeout of this transaction. |
void | setWaitOnLock(ObjectLock lock)
Indicates which lock this transaction is waiting for. |
void | softLock(Object object, int timeout)
Acquire a write lock on the object. |
static short | toDatabaseAccessMode(AccessMode mode)
Converts AccessMode constant to Database short constant |
protected void | txcommitted()
Inform all registered listeners that the transaction was committed. |
protected void | txrolledback()
Inform all registered listeners that the transaction was rolled back. |
void | update(LockEngine engine, ClassMolder molder, Object object, OID depended)
Update a new object in persistent storage and returns the
object's OID. |
void | writeLock(Object object, int timeout)
Acquire a write lock on the object. |
Parameters: object The object to record oid The object's OID engine The persistence engine used to create this object
Throws: TransactionAbortedException The transaction has been aborted due to inconsistency, duplicate object identity, error with the persistence engine or any other reason IllegalStateException This method has been called after the end of the transaction.
Throws: TransactionAbortedException The transaction could not close all the connections
Throws: TransactionAbortedException The transaction has been aborted due to inconsistency, duplicate object identity, error with the persistence engine or any other reason IllegalStateException This method has been called without calling {@link #prepare} first
Throws: TransactionAbortedException The transaction could not commit fully or partially and should be rolled back
Parameters: engine The persistence engine molder The molder of the creating class object The object to persist depended The master object's OID if exist
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: object The object to delete from persistent storage
Throws: ObjectNotPersistentException The object has not been queried or created in this transaction LockNotGrantedException Timeout or deadlock occured attempting to acquire lock on object PersistenceException An error reported by the persistence engine
Returns: the current ClassLoader's instance. null
if none
has been provided
Parameters: engine The persistence engine
Returns: An open connection
Throws: PersistenceException An error occured talking to the persistence engine
Parameters: object The object
Returns: The object's identity, or null
Parameters: engine The persistence engine used to create this object oid The object's OID
Returns: The object entry
Parameters: object The object to locate
Returns: The object's entry or null if not persistent
Returns: The lock which this transaction attempts to acquire
Parameters: object The object
Returns: True if persistent in transaction
This method is similar to {@link #fetch} 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.
Parameters: engine The persistence engine molder The class persistence molder object The object to fetch (single instance per transaction) identity The object's identity accessMode The access mode (see {@link AccessMode}) the values in persistent storage
Returns: object being loaded
Throws: LockNotGrantedException Timeout or deadlock occured attempting to acquire lock on object ObjectNotFoundException The object was not found in persistent storage PersistenceException An error reported by the persistence engine
This method work the same as {@link #load(LockEngine,ClassMolder,Object,Object,AccessMode)}, except a QueryResults can be specified.
Parameters: engine The persistence engine molder The class persistence molder object The object to fetch (single instance per transaction) identity The object's identity accessMode The access mode (see {@link AccessMode}) the values in persistent storage results The QueryResult that the data to be loaded from.
Returns: object being loaded
Throws: LockNotGrantedException Timeout or deadlock occured attempting to acquire lock on object ObjectNotFoundException The object was not found in persistent storage PersistenceException An error reported by the persistence engine
Parameters: engine The persistence engine object The object to persist
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
Update will also mark object to be created if the TIMESTAMP equals to NO_TIMESTAMP.
Parameters: engine The persistence engine molder The object's molder object The object to persist depended The master objects of the specified object to be created if exisit
Returns: true if the object is marked to be created
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 ObjectModifiedException Dirty checking mechanism may immediately report that the object was modified in the database during the long transaction.
Returns: True if the transaction can commit, false if the transaction is read only
Throws: IllegalStateException Method called if transaction is not in the proper state to perform this operation TransactionAbortedException The transaction has been aborted due to inconsistency, duplicate object identity, error with the persistence engine or any other reason
Parameters: engine The persistence engine query A query against the persistence engine accessMode The access mode
Returns: A query result iterator
Throws: QueryException An invalid query PersistenceException An error reported by the persistence engine
Parameters: object The object to release the lock
Throws: ObjectNotPersistentException The object was not queried or created in this transaction PersistenceException An error occured talking to the persistence engine
Parameters: object The object to remove
Returns: The removed entry
See Also: TransactionContext
The interceptor is a callback that notifies data objects on persistent state events.
If callback interceptor is not overrided, events will be sent to data object that implements the org.exolab.castor.jdo.Persistent interface.
Parameters: callback The callback interceptor, null if disabled
The factory is used to obatain a new instance of data object when it is needed during loading.
Parameters: instanceFactory The instanceFactory to be used, null if disable
Parameters: lock The lock which this transaction attempts to acquire
Parameters: 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
Throws: ObjectNotPersistentException The object has not been queried or created in this transaction LockNotGrantedException Timeout or deadlock occured attempting to acquire lock on object
Update will also mark object to be created if the TIMESTAMP equals to NO_TIMESTAMP.
Parameters: engine The persistence engine molder The object's molder object The object to persist depended The master objects of the specified object to be created if exisit
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 ObjectModifiedException Dirty checking mechanism may immediately report that the object was modified in the database during the long transaction.
Parameters: 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
Throws: ObjectNotPersistentException The object has not been queried or created in this transaction LockNotGrantedException Timeout or deadlock occured attempting to acquire lock on object PersistenceException An error reported by the persistence engine