| org.jpox.Transaction
All known Subclasses: org.jpox.TransactionImpl,
| Transaction | | public interface Transaction (Code) | | Representation of a transaction within JPOX. This interface is not
user application visible.
Handling of transactions in JPOX is split in 4 layers:
API - The User Visible Transaction API
ObjectManager Transaction - The Transaction assigned to a ObjectManager
X/Open/JTA - The Transaction Manager associated to the underlying datastore transaction
Resource - The Transaction handled by the datastore
In the the API layer, there are interfaces provided to the user application, as such:
javax.jdo.Transaction - the JDO API interface
javax.persistence.EntityTransaction - the JPA API interface
javax.transaction.UserTransaction - the JTA API interface
In the ObjectManager layer, the
org.jpox.Transaction interface defines the contract
for handling transactions for the ObjectManager.
In the X/Open/JTA layer the handling of XA resources is done. It means, XAResources are
obtained and enlisted to a TransactionManager. The TransactionManager will commit or rollback the resources
at the end of the transactions. There are two kinds of TransactionManager: JPOX and JTA. A
JTA TransactionManager is external to JPOX, while the JPOX TransactionManager is implemented
by JPOX as
org.jpox.transaction . The JPOX TransactionManager is used when the DataSource used
to obtain connections to the underlying database is not enlisted in an external JTA TransactionManager.
The JTA TransactionManager is usually found when running in J2EE application servers, however
nowadays there are many JTA containers that can be used in J2SE.
The scenarios where a JTA TransactionManager is used is:
When an JTA TransactionManager exists, and the connections to the underlying databases
are acquired via transactional DataSources. That means, when you ask a connection to the DataSource,
it will automatically enlist it in a JTA TransactionManager.
The Resource layer is handled by the datastore. For example, with RDBMS databases,
the javax.sql.Connection is the API used to demarcate the database transactions. In The RBDMS database,
the resource layer, it is handling the database transaction.
version:
$Revision: 1.27 $ |
| Method Summary | |
| void | addTransactionEventListener(TransactionEventListener listener)
| | void | begin()
Begin a transaction. | | void | commit()
Commit the current transaction. | | void | end()
Method to allow the transaction to flush any resources. | | void | flush()
Method to allow the transaction to flush any resources. | | boolean | getNontransactionalRead()
If true, allows persistent instances to be read without
a transaction active. | | boolean | getNontransactionalWrite()
If true, allows persistent instances to be written without
a transaction active. | | boolean | getOptimistic()
Optimistic transactions do not hold data store locks until commit time. | | Map | getOptions()
| | boolean | getRestoreValues()
Return the current value of the restoreValues property. | | boolean | getRetainValues()
If true, at commit time instances retain their field values. | | boolean | getRollbackOnly()
Returns the rollback-only status of the transaction. | | Synchronization | getSynchronization()
The user-specified Synchronization instance for this
Transaction instance. | | boolean | isActive()
Returns whether there is a transaction currently active. | | boolean | isCommitting()
Checks whether a transaction is committing. | | void | removeTransactionEventListener(TransactionEventListener listener)
| | void | rollback()
Rollback the current transaction. | | void | setNontransactionalRead(boolean nontransactionalRead)
If true, allow persistent instances to be read without
a transaction active. | | void | setNontransactionalWrite(boolean nontransactionalWrite)
If true, allow persistent instances to be written without
a transaction active. | | void | setOptimistic(boolean optimistic)
Optimistic transactions do not hold data store locks until commit time. | | void | setOption(String option, int value)
| | void | setOption(String option, boolean value)
| | void | setOption(String option, String value)
| | void | setRestoreValues(boolean restoreValues)
If true, at rollback, fields of newly persistent instances
are restored to their values as of the beginning of the transaction, and
the instances revert to transient. | | void | setRetainValues(boolean retainValues)
If true, at commit instances retain their values and the
instances transition to persistent-nontransactional. | | void | setRollbackOnly()
Sets the rollback-only status of the transaction to true. | | void | setSynchronization(Synchronization sync)
The user can specify a Synchronization instance to be
notified on transaction completions. |
| begin | | void begin()(Code) | | Begin a transaction.
The type of transaction (datastore/optimistic) is determined by the setting of the Optimistic flag.
throws:
JPOXUserException - if transactions are managed by a containerin the managed environment, or if the transaction is already active. |
| commit | | void commit()(Code) | | Commit the current transaction. The commit will trigger flushing the transaction, will
invoke the preCommit, commit the resources and invoke postCommit listeners.
If during flush or preCommit phases a JPOXUserException is raised, then the transaction will not
complete and the transaction remains active. The JPOXUserException is cascaded to the caller.
throws:
JPOXUserException - if transactions are managed by a containerin the managed environment, or if the transaction is not active. |
| end | | void end()(Code) | | Method to allow the transaction to flush any resources.
|
| flush | | void flush()(Code) | | Method to allow the transaction to flush any resources.
|
| getNontransactionalRead | | boolean getNontransactionalRead()(Code) | | If true, allows persistent instances to be read without
a transaction active.
Whether we are allowing non-tx reads |
| getNontransactionalWrite | | boolean getNontransactionalWrite()(Code) | | If true, allows persistent instances to be written without
a transaction active.
Whether we are allowing non-tx writes |
| getOptimistic | | boolean getOptimistic()(Code) | | Optimistic transactions do not hold data store locks until commit time.
the value of the Optimistic property. |
| getOptions | | Map getOptions()(Code) | | Obtain all settings for this Transaction
a map with settings |
| getRestoreValues | | boolean getRestoreValues()(Code) | | Return the current value of the restoreValues property.
the value of the restoreValues property |
| getRetainValues | | boolean getRetainValues()(Code) | | If true, at commit time instances retain their field values.
the value of the retainValues property |
| getRollbackOnly | | boolean getRollbackOnly()(Code) | | Returns the rollback-only status of the transaction.
When begun, the rollback-only status is false. Either the
application or the JDO implementation may set this flag
using setRollbackOnly.
Whether the transaction has been marked for rollback. |
| getSynchronization | | Synchronization getSynchronization()(Code) | | The user-specified Synchronization instance for this
Transaction instance.
the user-specified Synchronization instance. |
| isActive | | boolean isActive()(Code) | | Returns whether there is a transaction currently active.
Whether the transaction is active. |
| isCommitting | | boolean isCommitting()(Code) | | Checks whether a transaction is committing.
Whether the transaction is committing |
| rollback | | void rollback()(Code) | | Rollback the current transaction. The commit will trigger flushing the transaction, will
invoke the preRollback, rollback the resources and invoke postRollback listeners.
If during flush or preRollback phases a JPOXUserException is raised, then the transaction will not
complete and the transaction remains active. The JPOXUserException is cascaded to the caller.
throws:
JPOXUserException - if transactions are managed by a containerin the managed environment, or if the transaction is not active. |
| setNontransactionalRead | | void setNontransactionalRead(boolean nontransactionalRead)(Code) | | If true, allow persistent instances to be read without
a transaction active.
If an implementation does not support this option, a
Parameters:
nontransactionalRead - Whether to have non-tx reads
throws:
JPOXUserException - if not supported (supported by JPOX) |
| setNontransactionalWrite | | void setNontransactionalWrite(boolean nontransactionalWrite)(Code) | | If true, allow persistent instances to be written without
a transaction active.
Parameters:
nontransactionalWrite - Whether requiring non-tx writes
throws:
JPOXUserException - if not supported (JPOX doesnt support it!) |
| setOptimistic | | void setOptimistic(boolean optimistic)(Code) | | Optimistic transactions do not hold data store locks until commit time.
Parameters:
optimistic - the value of the Optimistic flag.
throws:
JPOXUserException - if not supported (JPOX supports it) |
| setOption | | void setOption(String option, boolean value)(Code) | | |
| setRestoreValues | | void setRestoreValues(boolean restoreValues)(Code) | | If true, at rollback, fields of newly persistent instances
are restored to their values as of the beginning of the transaction, and
the instances revert to transient. Additionally, fields of modified
instances of primitive types and immutable reference types
are restored to their values as of the beginning of the
transaction.
If false, at rollback, the values of fields of
newly persistent instances are unchanged and the instances revert to
transient. Additionally, dirty instances transition to hollow.
Parameters:
restoreValues - the value of the restoreValues property
throws:
JPOXUserException - if not supported (JPOX supports it) |
| setRetainValues | | void setRetainValues(boolean retainValues)(Code) | | If true, at commit instances retain their values and the
instances transition to persistent-nontransactional.
Parameters:
retainValues - the value of the retainValues property
throws:
JPOXUserException - if not supported (JPOX supports it) |
| setRollbackOnly | | void setRollbackOnly()(Code) | | Sets the rollback-only status of the transaction to true.
After this flag is set to true, the transaction
can no longer be committed.
throws:
JPOXUserException - if the flag is true and an attempt is madeto commit the txn |
| setSynchronization | | void setSynchronization(Synchronization sync)(Code) | | The user can specify a Synchronization instance to be
notified on transaction completions. The beforeCompletion
method is called prior to flushing instances to the data store.
The afterCompletion method is called after performing
state transitions of persistent and transactional instances, following
the data store commit or rollback operation.
Only one Synchronization instance can be registered with
the Transaction. If the application requires more than one
instance to receive synchronization callbacks, then the single
application instance is responsible for managing them, and forwarding
callbacks to them.
Parameters:
sync - the Synchronization instance to be notified;null for none |
|
|