org.datanucleus
Interface Transaction

All Known Implementing Classes:

JTAJCATransactionImpl, JTATransactionImpl, TransactionImpl

public interface Transaction

Representation of a transaction within DataNucleus. This interface is not user application visible. Handling of transactions in DataNucleus 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:

Transaction - the JDO API interface

javax.persistence.EntityTransaction - the JPA API interface

UserTransaction - the JTA API interface

UserTransaction - DataNucleus API proprietary API

In the ObjectManager layer, the 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: DataNucleus and JTA. A JTA TransactionManager is external to DataNucleus, while the DataNucleus TransactionManager is implemented by DataNucleus as org.datanucleus.transaction. The DataNucleus 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.

Field Summary

static java.lang.String

TRANSACTION_ISOLATION_OPTION Option to use when wanting to set the transaction isolation level.

Method Summary

void	addTransactionEventListener(TransactionEventListener listener) Adds a transaction listener.
void	begin() Begin a transaction.
void	bindTransactionEventListener(TransactionEventListener listener) Listeners that are never cleared, and invoked for all transactions
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.
java.util.Map<java.lang.String,java.lang.Object>	getOptions() Obtain all settings for this Transaction
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.
java.lang.Boolean	getSerializeRead() Accessor for the setting for whether to serialize read objects (lock them).
javax.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.
boolean	lockReadObjects() Convenience accessor providing a simple true/false for locking read objects.
void	removeTransactionEventListener(TransactionEventListener listener) Removes the listeners for a single transaction
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(java.lang.String option, boolean value)
void	setOption(java.lang.String option, int value)
void	setOption(java.lang.String option, java.lang.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	setSerializeRead(java.lang.Boolean serializeRead) Mutator for whether to serialize (lock) any read objects in this transaction.
void	setSynchronization(javax.transaction.Synchronization sync) The user can specify a Synchronization instance to be notified on transaction completions.

Field Detail

TRANSACTION_ISOLATION_OPTION

static final java.lang.String TRANSACTION_ISOLATION_OPTION

Option to use when wanting to set the transaction isolation level.

See Also:

Constant Field Values

Method Detail

begin

void begin()

Begin a transaction. The type of transaction (datastore/optimistic) is determined by the setting of the Optimistic flag.

Throws:

NucleusUserException - if transactions are managed by a container in the managed environment, or if the transaction is already active.

commit

void commit()

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 NucleusUserException is raised, then the transaction will not complete and the transaction remains active. The NucleusUserException is cascaded to the caller.

Throws:

NucleusUserException - if transactions are managed by a container in the managed environment, or if the transaction is not active.

rollback

void rollback()

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 NucleusUserException is raised, then the transaction will not complete and the transaction remains active. The NucleusUserException is cascaded to the caller.

Throws:

NucleusUserException - if transactions are managed by a container in the managed environment, or if the transaction is not active.

isActive

boolean isActive()

Returns whether there is a transaction currently active.

Returns:

Whether the transaction is active.

flush

void flush()

Method to allow the transaction to flush any resources.

end

void end()

Method to allow the transaction to flush any resources.

getRollbackOnly

boolean getRollbackOnly()

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.

Returns:

Whether the transaction has been marked for rollback.

setRollbackOnly

void setRollbackOnly()

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:

NucleusUserException - if the flag is true and an attempt is made to commit the txn

setNontransactionalRead

void setNontransactionalRead(boolean nontransactionalRead)

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:

NucleusUserException - if not supported (supported by DataNucleus)

getNontransactionalRead

boolean getNontransactionalRead()

If true, allows persistent instances to be read without a transaction active.

Returns:

Whether we are allowing non-tx reads

setNontransactionalWrite

void setNontransactionalWrite(boolean nontransactionalWrite)

If true, allow persistent instances to be written without a transaction active.

Parameters:

nontransactionalWrite - Whether requiring non-tx writes

Throws:

NucleusUserException - if not supported (DataNucleus doesnt support it!)

getNontransactionalWrite

boolean getNontransactionalWrite()

If true, allows persistent instances to be written without a transaction active.

Returns:

Whether we are allowing non-tx writes

setRetainValues

void setRetainValues(boolean retainValues)

If true, at commit instances retain their values and the instances transition to persistent-nontransactional.

Parameters:

retainValues - the value of the retainValues property

Throws:

NucleusUserException - if not supported (DataNucleus supports it)

getRetainValues

boolean getRetainValues()

If true, at commit time instances retain their field values.

Returns:

the value of the retainValues property

setRestoreValues

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. 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:

NucleusUserException - if not supported (DataNucleus supports it)

getRestoreValues

boolean getRestoreValues()

Return the current value of the restoreValues property.

Returns:

the value of the restoreValues property

setOptimistic

void setOptimistic(boolean optimistic)

Optimistic transactions do not hold data store locks until commit time.

Parameters:

optimistic - the value of the Optimistic flag.

Throws:

NucleusUserException - if not supported (DataNucleus supports it)

getOptimistic

boolean getOptimistic()

Optimistic transactions do not hold data store locks until commit time.

Returns:

the value of the Optimistic property.

setSynchronization

void setSynchronization(javax.transaction.Synchronization sync)

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

getSynchronization

javax.transaction.Synchronization getSynchronization()

The user-specified Synchronization instance for this Transaction instance.

Returns:

the user-specified Synchronization instance.

isCommitting

boolean isCommitting()

Checks whether a transaction is committing.

Returns:

Whether the transaction is committing

addTransactionEventListener

void addTransactionEventListener(TransactionEventListener listener)

Adds a transaction listener. After commit or rollback, listeners are cleared

Parameters:

listener -

removeTransactionEventListener

void removeTransactionEventListener(TransactionEventListener listener)

Removes the listeners for a single transaction

Parameters:

listener -

bindTransactionEventListener

void bindTransactionEventListener(TransactionEventListener listener)

Listeners that are never cleared, and invoked for all transactions

Parameters:

listener -

getOptions

java.util.Map<java.lang.String,java.lang.Object> getOptions()

Obtain all settings for this Transaction

Returns:

a map with settings

setSerializeRead

void setSerializeRead(java.lang.Boolean serializeRead)

Mutator for whether to serialize (lock) any read objects in this transaction.

Parameters:

serializeRead - Whether to serialise (lock) any read objects

getSerializeRead

java.lang.Boolean getSerializeRead()

Accessor for the setting for whether to serialize read objects (lock them).

Returns:

the value of the serializeRead property

lockReadObjects

boolean lockReadObjects()

Convenience accessor providing a simple true/false for locking read objects.

Returns:

Whether to lock read objects

setOption

void setOption(java.lang.String option,
               int value)

setOption

void setOption(java.lang.String option,
               boolean value)

setOption

void setOption(java.lang.String option,
               java.lang.String value)