Interface Transaction
-
public interface Transaction
The JDOTransaction
interface provides for initiation and completion of transactions under user control. It is a sub-interface of thePersistenceManager
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.- Version:
- 3.0
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
begin()
Begin a transaction.void
commit()
Commit the current transaction.String
getIsolationLevel()
Get the value for transaction isolation level for this transaction.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
getOptimistic()
Optimistic transactions do not hold data store locks until commit time.PersistenceManager
getPersistenceManager()
TheTransaction
instance is always associated with exactly onePersistenceManager
.boolean
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()
Return the current value of the serializeRead property.Synchronization
getSynchronization()
The user-specifiedSynchronization
instance for thisTransaction
instance.boolean
isActive()
Returns whether there is a transaction currently active.void
rollback()
Roll back the current transaction.void
setIsolationLevel(String level)
Set the value for transaction isolation level for this transaction.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
setOptimistic(boolean optimistic)
Optimistic transactions do not hold data store locks until commit time.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
setSerializeRead(Boolean serialize)
Iftrue
, a lock will be applied to all objects read in this transaction.void
setSynchronization(Synchronization sync)
The user can specify aSynchronization
instance to be notified on transaction completions.
-
-
-
Method Detail
-
begin
void begin()
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.- See Also:
setOptimistic(boolean)
,getOptimistic()
-
commit
void commit()
Commit the current transaction.- Throws:
JDOUserException
- if transactions are managed by a container in the managed environment, or if the transaction is not active.
-
rollback
void rollback()
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.
-
isActive
boolean isActive()
Returns whether there is a transaction currently active.- Returns:
true
if the transaction is active.
-
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:
true
if the transaction has been marked for rollback.- Since:
- 2.0
-
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, and any attempt to commit the transaction will throwJDOFatalDataStoreException
.- Since:
- 2.0
-
setNontransactionalRead
void setNontransactionalRead(boolean nontransactionalRead)
Iftrue
, allow persistent instances to be read without a transaction active. If an implementation does not support this option, aJDOUnsupportedOptionException
is thrown.- Parameters:
nontransactionalRead
- the value of the nontransactionalRead property
-
getNontransactionalRead
boolean getNontransactionalRead()
Iftrue
, allows persistent instances to be read without a transaction active.- Returns:
- the value of the nontransactionalRead property
-
setNontransactionalWrite
void setNontransactionalWrite(boolean nontransactionalWrite)
Iftrue
, allow persistent instances to be written without a transaction active. If an implementation does not support this option, aJDOUnsupportedOptionException
is thrown.- Parameters:
nontransactionalWrite
- the value of the nontransactionalRead property
-
getNontransactionalWrite
boolean getNontransactionalWrite()
Iftrue
, allows persistent instances to be written without a transaction active.- Returns:
- the value of the nontransactionalWrite property
-
setRetainValues
void setRetainValues(boolean retainValues)
Iftrue
, at commit instances retain their values and the instances transition to persistent-nontransactional. If an implementation does not support this option, aJDOUnsupportedOptionException
is thrown.- Parameters:
retainValues
- the value of the retainValues property
-
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. If an implementation does not support this option, aJDOUnsupportedOptionException
is thrown.- Parameters:
restoreValues
- the value of the restoreValues property
-
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. If an implementation does not support this option, aJDOUnsupportedOptionException
is thrown.- Parameters:
optimistic
- the value of the Optimistic flag.
-
getOptimistic
boolean getOptimistic()
Optimistic transactions do not hold data store locks until commit time.- Returns:
- the value of the Optimistic property.
-
getIsolationLevel
String getIsolationLevel()
Get the value for transaction isolation level for this transaction.- Returns:
- the transaction isolation level
- Since:
- 2.2
- See Also:
setIsolationLevel(String)
-
setIsolationLevel
void setIsolationLevel(String level)
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:
- 2.2
- See Also:
getIsolationLevel()
,Constants.TX_READ_UNCOMMITTED
,Constants.TX_READ_COMMITTED
,Constants.TX_REPEATABLE_READ
,Constants.TX_SNAPSHOT
,Constants.TX_SERIALIZABLE
-
setSynchronization
void setSynchronization(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
Synchronization getSynchronization()
The user-specifiedSynchronization
instance for thisTransaction
instance.- Returns:
- the user-specified
Synchronization
instance.
-
getPersistenceManager
PersistenceManager getPersistenceManager()
TheTransaction
instance is always associated with exactly onePersistenceManager
.- Returns:
- the
PersistenceManager
for thisTransaction
instance
-
setSerializeRead
void setSerializeRead(Boolean serialize)
Iftrue
, a lock will be applied to all objects read in this transaction.If
false
then retrieved objects will not be locked. If null will fallback to the value for metadata for the class in question.- Parameters:
serialize
- the value of the serializeRead property- Since:
- 3.0
-
getSerializeRead
Boolean getSerializeRead()
Return the current value of the serializeRead property.- Returns:
- the value of the serializeRead property
- Since:
- 3.0
-
-