com.sleepycat.je

Class Transaction

java.lang.Object

com.sleepycat.je.Transaction

public class Transaction
extends java.lang.Object

The Transaction object is the handle for a transaction. Methods off the transaction handle are used to configure, abort and commit the transaction. Transaction handles are provided to other Berkeley DB methods in order to transactionally protect those operations.

Transaction handles are free-threaded; transactions handles may be used concurrently by multiple threads. Once the Transaction.abort or Transaction.commit methods are called, the handle may not be accessed again, regardless of the success or failure of the method.

To obtain a transaction with default attributes:

     Transaction txn = myEnvironment.beginTransaction(null, null);
 

To customize the attributes of a transaction:

     TransactionConfig config = new TransactionConfig();
     config.setReadUncommitted(true);
     Transaction txn = myEnvironment.beginTransaction(null, config);
 

Constructor Summary

Constructors

Constructor and Description
Transaction(Environment env, Txn txn) Creates a transaction.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() Cause an abnormal termination of the transaction.
void	commit() End the transaction.
void	commit(Durability durability)
void	commitNoSync() End the transaction, not committing synchronously.
void	commitSync() End the transaction, committing synchronously.
void	commitWriteNoSync() End the transaction, committing synchronously.
boolean	equals(java.lang.Object o)
long	getId() Return the transaction's unique ID.
(package private) Locker	getLocker() This method should only be called by the LockerFactory.getReadableLocker and getWritableLocker methods.
java.lang.String	getName() Get the user visible name for the transaction.
boolean	getPrepared()
(package private) Txn	getTxn()
int	hashCode()
void	setLockTimeout(long timeOut) Configure the lock request timeout value for the transaction.
void	setName(java.lang.String name) Set the user visible name for the transaction.
void	setTxnTimeout(long timeOut) Configure the timeout value for the transaction lifetime.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Transaction

Transaction(Environment env,
           Txn txn)

Creates a transaction.

Method Detail

abort

public void abort()
           throws DatabaseException

Cause an abnormal termination of the transaction.

The log is played backward, and any necessary undo operations are done. Before Transaction.abort returns, any locks held by the transaction will have been released.

In the case of nested transactions, aborting a parent transaction causes all children (unresolved or not) of the parent transaction to be aborted.

All cursors opened within the transaction must be closed before the transaction is aborted.

After Transaction.abort has been called, regardless of its return, the Transaction handle may not be accessed again.

Throws:

DatabaseException - if a failure occurs.

getId

public long getId()
           throws DatabaseException

Return the transaction's unique ID.

Returns:

The transaction's unique ID.

Throws:

DatabaseException - if a failure occurs.

commit

public void commit()
            throws DatabaseException

End the transaction. If the environment is configured for synchronous commit, the transaction will be committed synchronously to stable storage before the call returns. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

If the environment is not configured for synchronous commit, the commit will not necessarily have been committed to stable storage before the call returns. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but it is possible this transaction may be undone during recovery.

All cursors opened within the transaction must be closed before the transaction is committed.

After this method returns the Transaction handle may not be accessed again, regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

Throws:

DatabaseException - if a failure occurs.

commit

public void commit(Durability durability)
            throws DatabaseException

Parameters:

durability - the durability requirements for this transaction

Throws:

DatabaseException - if a failure occurs.

commitSync

public void commitSync()
                throws DatabaseException

End the transaction, committing synchronously. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

This behavior is the default for database environments unless otherwise configured using the EnvironmentConfig.setTxnNoSync method. This behavior may also be set for a single transaction using the Environment.beginTransaction method. Any value specified to this method overrides both of those settings.

All cursors opened within the transaction must be closed before the transaction is committed.

After this method returns the Transaction handle may not be accessed again, regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

Throws:

DatabaseException - if a failure occurs.

commitNoSync

public void commitNoSync()
                  throws DatabaseException

End the transaction, not committing synchronously. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but it is possible this transaction may be undone during recovery.

This behavior may be set for a database environment using the EnvironmentConfig.setTxnNoSync method or for a single transaction using the Environment.beginTransaction method. Any value specified to this method overrides both of those settings.

All cursors opened within the transaction must be closed before the transaction is committed.

After this method returns the Transaction handle may not be accessed again, regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

Throws:

DatabaseException - if a failure occurs.

commitWriteNoSync

public void commitWriteNoSync()
                       throws DatabaseException

End the transaction, committing synchronously. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

This behavior is the default for database environments unless otherwise configured using the EnvironmentConfig.setTxnNoSync method. This behavior may also be set for a single transaction using the Environment.beginTransaction method. Any value specified to this method overrides both of those settings.

All cursors opened within the transaction must be closed before the transaction is committed.

After this method returns the Transaction handle may not be accessed again, regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

Throws:

DatabaseException - if a failure occurs.

getPrepared

public boolean getPrepared()

setTxnTimeout

public void setTxnTimeout(long timeOut)
                   throws java.lang.IllegalArgumentException,
                          DatabaseException

Configure the timeout value for the transaction lifetime.

If the transaction runs longer than this time, the transaction may throw DatabaseException.

Timeouts are checked whenever a thread of control blocks on a lock or when deadlock detection is performed. For this reason, the accuracy of the timeout depends on how often deadlock detection is performed.

Parameters:

timeOut - The timeout value for the transaction lifetime, in microseconds. A value of 0 disables timeouts for the transaction.

Throws:

java.lang.IllegalArgumentException - If the value of timeout is negative

DatabaseException - if a failure occurs.

setLockTimeout

public void setLockTimeout(long timeOut)
                    throws java.lang.IllegalArgumentException,
                           DatabaseException

Configure the lock request timeout value for the transaction.

If a lock request cannot be granted in this time, the transaction may throw DatabaseException.

Timeouts are checked whenever a thread of control blocks on a lock or when deadlock detection is performed. For this reason, the accuracy of the timeout depends on how often deadlock detection is performed.

Parameters:

timeOut - The lock request timeout value for the transaction, in microseconds. A value of 0 disables timeouts for the transaction.

This method may be called at any time during the life of the application.

Throws:

java.lang.IllegalArgumentException - If the value of timeout is negative.

DatabaseException - if a failure occurs.

setName

public void setName(java.lang.String name)

Set the user visible name for the transaction.

Parameters:

name - The user visible name for the transaction.

getName

public java.lang.String getName()

Get the user visible name for the transaction.

Returns:

The user visible name for the transaction.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getLocker

Locker getLocker()
           throws DatabaseException

This method should only be called by the LockerFactory.getReadableLocker and getWritableLocker methods. The locker returned does not enforce the readCommitted isolation setting.

Throws:

DatabaseException

getTxn

Txn getTxn()