Interface Transaction
-
- All Known Implementing Classes:
JTAJCATransactionImpl
,JTATransactionImpl
,TransactionImpl
public interface Transaction
Representation of an ExecutionContext transaction within DataNucleus. This interface is not user application visible. Handling of transactions in DataNucleus is split into 4 layers:- API - The User Visible Transaction API
- ExecutionContext Transaction - The Transaction assigned to an ExecutionContext
- X/Open/JTA - The ResourcedTransactionManager managing ResourcedTransaction associated to the underlying datastore transaction
- Resource - The Transaction handled by the datastore
- JDO Transaction - the JDO API interface
- JPA EntityTransaction - the JPA API interface
UserTransaction
- the JTA API interface
Transaction
interface defines the contract for handling transactions for the ExecutionContext.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 JavaEE application servers, however nowadays there are many JTA containers that can be used in JavaSE.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 an RBDMS database, the resource layer is handling the database transaction. For a treatment of isolation levels, refer to http://www.cs.umb.edu/~poneil/iso.pdf
-
-
Field Summary
Fields Modifier and Type Field Description static String
TRANSACTION_ISOLATION_OPTION
Option to use when wanting to set the transaction isolation level.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description 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 transactionsvoid
close()
Method to inform the transaction that it is closed.void
commit()
Commit the current transaction.void
end()
Method to notify that the transaction is ended.void
flush()
Method to allow the transaction to flush any resources.long
getBeginTime()
Accessor for the time (millisecs) from System.currentTimeMillis when the transaction started.boolean
getIsActive()
Return whether the transaction is active and return immediately.boolean
getNontransactionalRead()
Iftrue
, allows persistent instances to be read without a transaction active.boolean
getNontransactionalWrite()
Iftrue
, allows persistent instances to be written without a transaction active.boolean
getNontransactionalWriteAutoCommit()
Whether to auto-commit any non-tx writes.boolean
getOptimistic()
Optimistic transactions do not hold data store locks until commit time.Map<String,Object>
getOptions()
Obtain all settings for this Transactionboolean
getRestoreValues()
Return the current value of the restoreValues property.boolean
getRetainValues()
Iftrue
, at commit time instances retain their field values.boolean
getRollbackOnly()
Returns the rollback-only status of the transaction.Boolean
getSerializeRead()
Accessor for the setting for whether to serialize read objects (lock them).javax.transaction.Synchronization
getSynchronization()
The user-specifiedSynchronization
instance for thisTransaction
instance.boolean
isActive()
Returns whether there is a transaction currently active.boolean
isCommitting()
Checks whether a transaction is committing.void
preFlush()
Method to notify that flush is started.void
releaseSavepoint(String name)
Method to deregister the current position as a savepoint with the provided name (assuming the datastore supports it).void
removeTransactionEventListener(TransactionEventListener listener)
Removes the specified listener.void
rollback()
Rollback the current transaction.void
rollbackToSavepoint(String name)
Method to rollback the transaction to the specified savepoint (assuming the datastore supports it).void
setNontransactionalRead(boolean nontransactionalRead)
Iftrue
, allow persistent instances to be read without a transaction active.void
setNontransactionalWrite(boolean nontransactionalWrite)
Iftrue
, allow persistent instances to be written without a transaction active.void
setNontransactionalWriteAutoCommit(boolean autoCommit)
Set whether to auto-commit any non-tx writes.void
setOptimistic(boolean optimistic)
Optimistic transactions do not hold data store locks until commit time.void
setOption(String option, boolean value)
void
setOption(String option, int value)
void
setOption(String option, Object value)
void
setOption(String option, String value)
void
setRestoreValues(boolean restoreValues)
Iftrue
, 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)
Iftrue
, at commit instances retain their values and the instances transition to persistent-nontransactional.void
setRollbackOnly()
Sets the rollback-only status of the transaction totrue
.void
setSavepoint(String name)
Method to register the current position as a savepoint with the provided name (assuming the datastore supports it).void
setSerializeRead(Boolean serializeRead)
Mutator for whether to serialize (lock) any read objects in this transaction.void
setSynchronization(javax.transaction.Synchronization sync)
The user can specify aSynchronization
instance to be notified on transaction completions.
-
-
-
Field Detail
-
TRANSACTION_ISOLATION_OPTION
static final String TRANSACTION_ISOLATION_OPTION
Option to use when wanting to set the transaction isolation level.- See Also:
- Constant Field Values
-
-
Method Detail
-
close
void close()
Method to inform the transaction that it is closed. This is only necessary for JBoss usage of JPA where it doesn't bother calling afterCompletion on the JTA txn until after it closes the EntityManager so we need a hook to inform the transaction that it is closed so ignore any subsequent afterCompletion.
-
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. This can also attempt to join to any underlying transaction if the implementation requires it. UsegetIsActive
if you just want the active flag.- Returns:
- Whether the transaction is active.
-
getIsActive
boolean getIsActive()
Return whether the transaction is active and return immediately.- Returns:
- Whether it is active
-
getBeginTime
long getBeginTime()
Accessor for the time (millisecs) from System.currentTimeMillis when the transaction started.- Returns:
- Time at which the transaction started. -1 implies not yet started.
-
preFlush
void preFlush()
Method to notify that flush is started.
-
flush
void flush()
Method to allow the transaction to flush any resources.
-
end
void end()
Method to notify that the transaction is ended.
-
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 totrue
. After this flag is set totrue
, 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)
Iftrue
, allow persistent instances to be read without a transaction active. If an implementation does not support this option, a NucleusUserException is thrown.- Parameters:
nontransactionalRead
- Whether to have non-tx reads- Throws:
NucleusUserException
- if not supported
-
getNontransactionalRead
boolean getNontransactionalRead()
Iftrue
, allows persistent instances to be read without a transaction active.- Returns:
- Whether we are allowing non-tx reads
-
setNontransactionalWrite
void setNontransactionalWrite(boolean nontransactionalWrite)
Iftrue
, allow persistent instances to be written without a transaction active.- Parameters:
nontransactionalWrite
- Whether requiring non-tx writes- Throws:
NucleusUserException
- if not supported
-
getNontransactionalWrite
boolean getNontransactionalWrite()
Iftrue
, allows persistent instances to be written without a transaction active.- Returns:
- Whether we are allowing non-tx writes
-
setNontransactionalWriteAutoCommit
void setNontransactionalWriteAutoCommit(boolean autoCommit)
Set whether to auto-commit any non-tx writes.- Parameters:
autoCommit
- Whether to auto-commit any non-tx writes- Throws:
NucleusUserException
- if not supported
-
getNontransactionalWriteAutoCommit
boolean getNontransactionalWriteAutoCommit()
Whether to auto-commit any non-tx writes.- Returns:
- Whether to auto-commit any non-tx writes.
-
setRetainValues
void setRetainValues(boolean retainValues)
Iftrue
, 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
-
getRetainValues
boolean getRetainValues()
Iftrue
, at commit time instances retain their field values.- Returns:
- the value of the retainValues property
-
setRestoreValues
void setRestoreValues(boolean restoreValues)
Iftrue
, 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
-
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
-
getOptimistic
boolean getOptimistic()
Optimistic transactions do not hold data store locks until commit time.- Returns:
- the value of the Optimistic property.
-
setSerializeRead
void setSerializeRead(Boolean serializeRead)
Mutator for whether to serialize (lock) any read objects in this transaction.- Parameters:
serializeRead
- Whether to serialise (lock) any read objects
-
getSerializeRead
Boolean getSerializeRead()
Accessor for the setting for whether to serialize read objects (lock them).- Returns:
- the value of the serializeRead property
-
setSynchronization
void setSynchronization(javax.transaction.Synchronization sync)
The user can specify aSynchronization
instance to be notified on transaction completions. ThebeforeCompletion
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 theTransaction
. 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
- theSynchronization
instance to be notified;null
for none
-
getSynchronization
javax.transaction.Synchronization getSynchronization()
The user-specifiedSynchronization
instance for thisTransaction
instance.- Returns:
- the user-specified
Synchronization
instance.
-
isCommitting
boolean isCommitting()
Checks whether a transaction is committing.- Returns:
- Whether the transaction is committing
-
setSavepoint
void setSavepoint(String name)
Method to register the current position as a savepoint with the provided name (assuming the datastore supports it).- Parameters:
name
- Savepoint name
-
releaseSavepoint
void releaseSavepoint(String name)
Method to deregister the current position as a savepoint with the provided name (assuming the datastore supports it).- Parameters:
name
- Savepoint name
-
rollbackToSavepoint
void rollbackToSavepoint(String name)
Method to rollback the transaction to the specified savepoint (assuming the datastore supports it).- Parameters:
name
- Savepoint name
-
addTransactionEventListener
void addTransactionEventListener(TransactionEventListener listener)
Adds a transaction listener. After commit or rollback, listeners are cleared- Parameters:
listener
- The listener to add
-
removeTransactionEventListener
void removeTransactionEventListener(TransactionEventListener listener)
Removes the specified listener.- Parameters:
listener
- Listener to remove
-
bindTransactionEventListener
void bindTransactionEventListener(TransactionEventListener listener)
Listeners that are never cleared, and invoked for all transactions- Parameters:
listener
- listener to bind
-
getOptions
Map<String,Object> getOptions()
Obtain all settings for this Transaction- Returns:
- a map with settings
-
setOption
void setOption(String option, int value)
-
setOption
void setOption(String option, boolean value)
-
-