Transaction (DataNucleus Core 4.1.17-SNAPSHOT API)

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 into 4 layers:
- API - The User Visible Transaction API
- ExecutionContext Transaction - The Transaction assigned to an ExecutionContext
- 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:
- JDO Transaction - the JDO API interface
- JPA EntityTransaction - the JPA API interface
- UserTransaction - the JTA API interface
In the ExecutionContext layer, the 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 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. For a treatment of isolation levels, refer to http://www.cs.umb.edu/~poneil/iso.pdf

Field Summary

Fields
Modifier and Type Field and Description

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

Fields
Modifier and Type	Field and 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 and 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 transactions
`void`	`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.
`boolean`	`getIsActive()` Return whether the transaction is active and return immediately.
`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`	`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 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.
`Boolean`	`getSerializeRead()` Accessor for the setting for whether to serialize read objects (lock them).
`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`	`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)` 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`	`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)` 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`	`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(Synchronization sync)` The user can specify a `Synchronization` 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. Use
```
getIsActive
```
    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
  - 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 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 NucleusUserException is thrown.
    
    Parameters:
    
    nontransactionalRead - Whether to have non-tx reads
    
    Throws:
    
    NucleusUserException - if not supported
  - 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
  - getNontransactionalWrite
```
boolean getNontransactionalWrite()
```
    If true, 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)
```
    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
  - 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
  - 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(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
```
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
  - 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)
```
  - setOption
```
void setOption(String option,
               String value)
```
  - setOption
```
void setOption(String option,
               Object value)
```

Interface Transaction

Field Summary

Method Summary

Field Detail

TRANSACTION_ISOLATION_OPTION

Method Detail

close

begin

commit

rollback

isActive

getIsActive

preFlush

flush

end

getRollbackOnly

setRollbackOnly

setNontransactionalRead

getNontransactionalRead

setNontransactionalWrite

getNontransactionalWrite

setNontransactionalWriteAutoCommit

getNontransactionalWriteAutoCommit

setRetainValues

getRetainValues

setRestoreValues

getRestoreValues

setOptimistic

getOptimistic

setSerializeRead

getSerializeRead

setSynchronization

getSynchronization

isCommitting

setSavepoint

releaseSavepoint

rollbackToSavepoint

addTransactionEventListener

removeTransactionEventListener

bindTransactionEventListener

getOptions

setOption

setOption

setOption

setOption