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.

A single Transaction may be used to protect operations for any number of Databases in a given environment. However, a single Transaction may not be used for operations in more than one distinct environment.

Transaction handles are free-threaded; transactions handles may be used concurrently by multiple threads. Once the Transaction.abort or Transaction.commit method is called, the handle may not be accessed again, regardless of the success or failure of the method, with one exception: the abort method may be called any number of times to simplify error handling.

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);
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Transaction.State The current state of the transaction.

Method Summary

Modifier and Type	Method and Description
void	abort() Cause an abnormal termination of the transaction.
void	commit() End the transaction.
void	commit(Durability durability) End the transaction using the specified durability requirements.
void	commitNoSync() End the transaction, not writing to stable storage and not committing synchronously.
void	commitSync() End the transaction, writing to stable storage and committing synchronously.
void	commitWriteNoSync() End the transaction, writing to stable storage but not committing synchronously.
CommitToken	getCommitToken() This method is intended for use with a replicated environment.
long	getId() Return the transaction's unique ID.
long	getLockTimeout(java.util.concurrent.TimeUnit unit) Returns the lock request timeout value for the transaction.
java.lang.String	getName() Get the user visible name for the transaction.
Transaction.State	getState() Returns the current state of the transaction.
long	getTxnTimeout(java.util.concurrent.TimeUnit unit) Returns the timeout value for the transaction lifetime.
boolean	isValid() Returns whether this Transaction is open, which is equivalent to when getState() returns Transaction.State.OPEN.
void	setLockTimeout(long timeOut) Deprecated. as of 4.0, replaced by setLockTimeout(long, TimeUnit).
void	setLockTimeout(long timeOut, java.util.concurrent.TimeUnit unit) Configures 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) Deprecated. as of 4.0, replaced by setTxnTimeout(long, TimeUnit).
void	setTxnTimeout(long timeOut, java.util.concurrent.TimeUnit unit) Configures the timeout value for the transaction lifetime.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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 this method has been called, regardless of its return, the Transaction handle may not be accessed again, with one exception: the abort method itself may be called any number of times to simplify error handling.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the environment has been closed, or cursors associated with the transaction are still open.

DatabaseException

getId

public long getId()

Return the transaction's unique ID.

Returns:

The transaction's unique ID.

getCommitToken

public CommitToken getCommitToken()
                           throws java.lang.IllegalStateException

This method is intended for use with a replicated environment.

It returns the commitToken associated with a successful replicated commit. A null value is returned if the txn was not associated with a replicated environment, or the txn did not result in any changes to the environment. This method should only be called after the transaction has finished.

This method is typically used in conjunction with the CommitPointConsistencyPolicy.

Returns:

the token used to identify the replicated commit. Return null if the transaction has aborted, or has committed without making any updates.

Throws:

java.lang.IllegalStateException - if the method is called before the transaction has committed or aborted.

See Also:

CommitPointConsistencyPolicy

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.

If the method encounters an error, the transaction will have been aborted when the call returns.

After this method has been called, regardless of its return, the Transaction handle may not be accessed again, with one exception: the abort method may be called any number of times to simplify error handling.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Throws:

InsufficientReplicasException - if the master in a replicated environment could not contact a quorum of replicas as determined by the Durability.ReplicaAckPolicy.

InsufficientAcksException - if the master in a replicated environment did not receive enough replica acknowledgments, although the commit succeeded locally.

ReplicaWriteException - if a write operation was performed with this transaction, but this node is now a Replica.

OperationFailureException - if this exception occurred earlier and caused the transaction to be invalidated.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed, or cursors associated with the transaction are still open.

DatabaseException

commit

public void commit(Durability durability)
            throws DatabaseException

End the transaction using the specified durability requirements. This requirement overrides any default durability requirements associated with the environment. If the durability requirements cannot be satisfied, an exception is thrown to describe the problem. Please see Durability for specific exceptions that could result when the durability requirements cannot be satisfied.

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

If the method encounters an error, the transaction will have been aborted when the call returns.

After this method has been called, regardless of its return, the Transaction handle may not be accessed again, with one exception: the abort method may be called any number of times to simplify error handling.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Parameters:

durability - the durability requirements for this transaction

Throws:

InsufficientReplicasException - if the master in a replicated environment could not contact enough replicas to initiate the commit.

InsufficientAcksException - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.

ReplicaWriteException - if a write operation was performed with this transaction, but this node is now a Replica.

OperationFailureException - if this exception occurred earlier and caused the transaction to be invalidated.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed, or cursors associated with the transaction are still open.

java.lang.IllegalArgumentException - if an invalid parameter is specified.

DatabaseException

commitSync

public void commitSync()
                throws DatabaseException

End the transaction, writing to stable storage and 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.

If the method encounters an error, the transaction will have been aborted when the call returns.

After this method has been called, regardless of its return, the Transaction handle may not be accessed again, with one exception: the abort method may be called any number of times to simplify error handling.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Throws:

InsufficientReplicasException - if the master in a replicated environment could not contact enough replicas to initiate the commit.

InsufficientAcksException - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.

ReplicaWriteException - if a write operation was performed with this transaction, but this node is now a Replica.

OperationFailureException - if this exception occurred earlier and caused the transaction to be invalidated.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed, or cursors associated with the transaction are still open.

DatabaseException

commitNoSync

public void commitNoSync()
                  throws DatabaseException

End the transaction, not writing to stable storage and 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.

If the method encounters an error, the transaction will have been aborted when the call returns.

After this method has been called, regardless of its return, the Transaction handle may not be accessed again, with one exception: the abort method may be called any number of times to simplify error handling.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Throws:

InsufficientReplicasException - if the master in a replicated environment could not contact enough replicas to initiate the commit.

InsufficientAcksException - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.

ReplicaWriteException - if a write operation was performed with this transaction, but this node is now a Replica.

OperationFailureException - if this exception occurred earlier and caused the transaction to be invalidated.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed, or cursors associated with the transaction are still open.

DatabaseException

commitWriteNoSync

public void commitWriteNoSync()
                       throws DatabaseException

End the transaction, writing to stable storage but 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 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.

If the method encounters an error, the transaction will have been aborted when the call returns.

After this method has been called, regardless of its return, the Transaction handle may not be accessed again, with one exception: the abort method may be called any number of times to simplify error handling.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Throws:

InsufficientReplicasException - if the master in a replicated environment could not contact enough replicas to initiate the commit.

InsufficientAcksException - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.

ReplicaWriteException - if a write operation was performed with this transaction, but this node is now a Replica.

OperationFailureException - if this exception occurred earlier and caused the transaction to be invalidated.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed, or cursors associated with the transaction are still open.

DatabaseException

getTxnTimeout

public long getTxnTimeout(java.util.concurrent.TimeUnit unit)
                   throws EnvironmentFailureException,
                          java.lang.IllegalStateException,
                          java.lang.IllegalArgumentException

Returns the timeout value for the transaction lifetime.

If setTxnTimeout(long,TimeUnit) has not been called to configure the timeout, the environment configuration value (EnvironmentConfig.TXN_TIMEOUT )is returned.

Parameters:

unit - the TimeUnit of the returned value. May not be null.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed.

java.lang.IllegalArgumentException - if the unit is null.

Since:

4.0

setTxnTimeout

public void setTxnTimeout(long timeOut,
                          java.util.concurrent.TimeUnit unit)
                   throws java.lang.IllegalArgumentException,
                          DatabaseException

Configures the timeout value for the transaction lifetime.

If the transaction runs longer than this time, an operation using the transaction may throw TransactionTimeoutException. The transaction timeout is checked when locking a record, as part of a read or write operation.

A value of zero (which is the default) disables timeouts for the transaction, meaning that no limit on the duration of the transaction is enforced. Note that the setLockTimeout(long, TimeUnit) lock timeout} is independent of the transaction timeout, and the lock timeout should not normally be set to zero.

Parameters:

timeOut - The timeout value for the transaction lifetime, or zero to disable transaction timeouts.

unit - the TimeUnit of the timeOut value. May be null only if timeOut is zero.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed.

java.lang.IllegalArgumentException - if timeOut or unit is invalid.

DatabaseException

Since:

4.0

setTxnTimeout

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

Deprecated. as of 4.0, replaced by setTxnTimeout(long, TimeUnit).

Configures the timeout value for the transaction lifetime, with the timeout value specified in microseconds. This method is equivalent to:

setTxnTimeout(long, TimeUnit.MICROSECONDS);

Throws:

java.lang.IllegalArgumentException

DatabaseException

getLockTimeout

public long getLockTimeout(java.util.concurrent.TimeUnit unit)
                    throws EnvironmentFailureException,
                           java.lang.IllegalStateException,
                           java.lang.IllegalArgumentException

Returns the lock request timeout value for the transaction.

If setLockTimeout(long,TimeUnit) has not been called to configure the timeout, the environment configuration value (EnvironmentConfig.LOCK_TIMEOUT) is returned.

Parameters:

unit - the TimeUnit of the returned value. May not be null.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed.

java.lang.IllegalArgumentException - if the unit is null.

Since:

4.0

setLockTimeout

public void setLockTimeout(long timeOut,
                           java.util.concurrent.TimeUnit unit)
                    throws java.lang.IllegalArgumentException,
                           DatabaseException

Configures the lock request timeout value for the transaction. This overrides the default lock timeout.

A value of zero disables lock timeouts. This is not recommended, even when the application expects that deadlocks will not occur or will be easily resolved. A lock timeout is a fall-back that guards against unexpected "live lock", unresponsive threads, or application failure to close a cursor or to commit or abort a transaction.

Parameters:

timeOut - The lock timeout for all transactional and non-transactional operations, or zero to disable lock timeouts.

unit - the TimeUnit of the timeOut value. May be null only if timeOut is zero.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the transaction or environment has been closed.

java.lang.IllegalArgumentException - if timeOut or unit is invalid.

DatabaseException

Since:

4.0

setLockTimeout

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

Deprecated. as of 4.0, replaced by setLockTimeout(long, TimeUnit).

Configures the lock request timeout value for the transaction, with the timeout value specified in microseconds. This method is equivalent to:

setLockTimeout(long, TimeUnit.MICROSECONDS);

Throws:

java.lang.IllegalArgumentException

DatabaseException

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.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

isValid

public boolean isValid()

Returns whether this Transaction is open, which is equivalent to when getState() returns Transaction.State.OPEN. See Transaction.State.OPEN for more information.

When an OperationFailureException, or one of its subclasses, is caught, the isValid method may be called to determine whether the Transaction can continue to be used, or should be aborted.

getState

public Transaction.State getState()

Returns the current state of the transaction.

Since:

5.0.48