1064 words

javax.jdo.Transaction - JDO interface

javax.jdo
Interface Transaction

The JDO Transaction interface provides for initiation and completion of transactions under user control. It is a sub-interface of the PersistenceManager that deals with options and transaction demarcation.

Transaction options include whether optimistic concurrency control should be used for the current transaction, whether instances may hold values in the cache outside transactions, and whether values should be retained in the cache after transaction completion. These options are valid for both managed and non-managed transactions.

Transaction initiation and completion methods have similar semantics to javax.transaction.UserTransaction when used outside a managed environment. When used in a managed environment, transaction initiation and completion methods may only be used with bean-managed transaction semantics.

Since:
JDO 1.0
void begin()
Begin a transaction.
Begin a transaction. The type of transaction is determined by the setting of the Optimistic flag.
Throws:
JDOUserException - if transactions are managed by a container in the managed environment, or if the transaction is already active.
Since:
JDO 1.0
See Also:
setOptimistic
getOptimistic
void commit()
Commit the current transaction.
Commit the current transaction.
Throws:
JDOUserException - if transactions are managed by a container in the managed environment, or if the transaction is not active.
Since:
JDO 1.0
Get the value for transaction isolation level for this transaction.
Get the value for transaction isolation level for this transaction.
Returns:
the transaction isolation level
Since:
JDO 2.2
See Also:
setIsolationLevel(String)
If true, allows persistent instances to be read without a transaction active.
If true, allows persistent instances to be read without a transaction active.
Returns:
the value of the nontransactionalRead property
Since:
JDO 1.0
If true, allows persistent instances to be written without a transaction active.
If true, allows persistent instances to be written without a transaction active.
Returns:
the value of the nontransactionalWrite property
Since:
JDO 1.0
boolean getOptimistic()
Optimistic transactions do not hold data store locks until commit time.
Optimistic transactions do not hold data store locks until commit time.
Returns:
the value of the Optimistic property.
Since:
JDO 1.0
The Transaction instance is always associated with exactly one PersistenceManager.
The Transaction instance is always associated with exactly one PersistenceManager.
Returns:
the PersistenceManager for this Transaction instance
Since:
JDO 1.0
Return the current value of the restoreValues property.
Return the current value of the restoreValues property.
Returns:
the value of the restoreValues property
Since:
JDO 1.0
boolean getRetainValues()
If true, at commit time instances retain their field values.
If true, at commit time instances retain their field values.
Returns:
the value of the retainValues property
Since:
JDO 1.0
boolean getRollbackOnly()
Returns the rollback-only status of the transaction.
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:
true if the transaction has been marked for rollback.
Since:
JDO 2.0
Synchronization getSynchronization()
The user-specified Synchronization instance for this Transaction instance.
The user-specified Synchronization instance for this Transaction instance.
Returns:
the user-specified Synchronization instance.
Since:
JDO 1.0
boolean isActive()
Returns whether there is a transaction currently active.
Returns whether there is a transaction currently active.
Returns:
true if the transaction is active.
Since:
JDO 1.0
void rollback()
Roll back the current transaction.
Roll back the current transaction.
Throws:
JDOUserException - if transactions are managed by a container in the managed environment, or if the transaction is not active.
Since:
JDO 1.0
void setIsolationLevel(String level)
Set the value for transaction isolation level for this transaction.
Set the value for transaction isolation level for this transaction. Transaction isolation levels are defined in javax.jdo.Constants. If the requested level is not available, but a higher level is available, the higher level is silently used. If the requested level is not available, and no higher level is available, then JDOUnsupportedOptionException is thrown. Five standard isolation levels are defined. Other isolation levels might be supported by an implementation but are not standard.

Standard values in order of low to high are:

  • read-uncommitted
  • read-committed
  • repeatable-read
  • snapshot
  • serializable

Parameters:
level - the transaction isolation level
Since:
JDO 2.2
See Also:
getIsolationLevel()
Constants.TX_READ_UNCOMMITTED
Constants.TX_READ_COMMITTED
Constants.TX_REPEATABLE_READ
Constants.TX_SNAPSHOT
Constants.TX_SERIALIZABLE
void setNontransactionalRead(boolean nontransactionalRead)
If true, allow persistent instances to be read without a transaction active.
If true, allow persistent instances to be read without a transaction active. If an implementation does not support this option, a JDOUnsupportedOptionException is thrown.
Parameters:
nontransactionalRead - the value of the nontransactionalRead property
Since:
JDO 1.0
void setNontransactionalWrite(boolean nontransactionalWrite)
If true, allow persistent instances to be written without a transaction active.
If true, allow persistent instances to be written without a transaction active. If an implementation does not support this option, a JDOUnsupportedOptionException is thrown.
Parameters:
nontransactionalWrite - the value of the nontransactionalRead property
Since:
JDO 1.0
void setOptimistic(boolean optimistic)
Optimistic transactions do not hold data store locks until commit time.
Optimistic transactions do not hold data store locks until commit time. If an implementation does not support this option, a JDOUnsupportedOptionException is thrown.
Parameters:
optimistic - the value of the Optimistic flag.
Since:
JDO 1.0
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.
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. If an implementation does not support this option, a JDOUnsupportedOptionException is thrown.

Parameters:
restoreValues - the value of the restoreValues property
Since:
JDO 1.0
void setRetainValues(boolean retainValues)
If true, at commit instances retain their values and the instances transition to persistent-nontransactional.
If true, at commit instances retain their values and the instances transition to persistent-nontransactional. If an implementation does not support this option, a JDOUnsupportedOptionException is thrown.
Parameters:
retainValues - the value of the retainValues property
Since:
JDO 1.0
Sets the rollback-only status of the transaction to true.
Sets the rollback-only status of the transaction to true. After this flag is set to true, the transaction can no longer be committed, and any attempt to commit the transaction will throw JDOFatalDataStoreException.
Since:
JDO 2.0
void setSynchronization(Synchronization sync)
The user can specify a Synchronization instance to be notified on transaction completions.
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
Since:
JDO 1.0

This documentation page is derived (with some adjustments) from the JDO 2.2 API
and is available under the terms of the Apache License, v. 2.0.