com.amazon.carbonado

Interface Transaction

All Known Implementing Classes:

TransactionPair

public interface Transaction

Transactions define atomic operations which can be committed or aborted as a unit. Transactions are entered by calling Repository.enterTransaction(). Transactions are thread-local, and so no special action needs to be taken to bind operations to them. Cursors which are opened in the scope of a transaction are automatically closed when the transaction is committed or aborted.

Transactions do not exit when they are committed. The transaction is still valid after a commit, but new operations are grouped into a separate atomic unit. The exit method must be invoked on every transaction. The following pattern is recommended:

 Transaction txn = repository.enterTransaction();
 try {
     // Make updates to storage layer
     ...

     // Commit the changes up to this point
     txn.commit();

     // Optionally make more updates
     ...

     // Commit remaining changes
     txn.commit();
 } finally {
     // Ensure transaction exits, aborting uncommitted changes if an exception was thrown
     txn.exit();
 }
 

Transactions may be nested. Calling commit or abort on an outer transaction will recursively apply the same operation to all inner transactions as well. All Cursors contained within are also closed.

Transaction instances are mutable, but they are thread-safe.

Author:

Brian S O'Neill

Method Summary

Methods

Modifier and Type	Method and Description
void	attach() Attaches this transaction to the current thread, if it has been detached.
void	commit() If currently in a transaction, commits all changes to the storage layer since the last commit within the transaction.
void	detach() Detaches this transaction from the current thread.
void	exit() Closes the current transaction, aborting all changes since the last commit.
IsolationLevel	getIsolationLevel() Returns the isolation level of this transaction.
boolean	isForUpdate() Returns true if this transaction is in update mode, which is adjusted by calling setForUpdate(boolean).
boolean	preCommit() Calling this method commits all nested child transactions, closes all scoped cursors, and locks out some interactions from other threads.
void	setDesiredLockTimeout(int timeout, java.util.concurrent.TimeUnit unit) Specify a desired timeout for aquiring locks within this transaction.
void	setForUpdate(boolean forUpdate) Set to true to force all read operations within this transaction to acquire upgradable or write locks.

Method Detail

commit

void commit()
            throws PersistException

If currently in a transaction, commits all changes to the storage layer since the last commit within the transaction.

Throws:

PersistException - if storage layer throws an exception

exit

void exit()
          throws PersistException

Closes the current transaction, aborting all changes since the last commit.

Throws:

PersistException - if storage layer throws an exception

setForUpdate

void setForUpdate(boolean forUpdate)

Set to true to force all read operations within this transaction to acquire upgradable or write locks. This option eliminates deadlocks that may occur when updating records, except it may increase contention.

isForUpdate

boolean isForUpdate()

Returns true if this transaction is in update mode, which is adjusted by calling setForUpdate(boolean).

setDesiredLockTimeout

void setDesiredLockTimeout(int timeout,
                         java.util.concurrent.TimeUnit unit)

Specify a desired timeout for aquiring locks within this transaction. Calling this method may have have no effect at all, if the repository does not support this feature. In addition, the lock timeout might not be alterable if the transaction contains uncommitted data.

Also, the range of lock timeout values supported might be small. For example, only a timeout value of zero might be supported. In that case, the transaction is configured to not wait at all when trying to acquire locks. Expect immediate timeout exceptions when locks cannot be granted.

Nested transactions inherit the desired lock timeout of their parent. Top transactions always begin with the default lock timeout.

Parameters:

timeout - Desired lock timeout. If negative, revert lock timeout to default value.

unit - Time unit for timeout. If null, revert lock timeout to default value.

getIsolationLevel

IsolationLevel getIsolationLevel()

Returns the isolation level of this transaction.

detach

void detach()

Detaches this transaction from the current thread. It can be attached later, and to any thread which currently has no thread-local transaction.

Detaching a transaction also detaches any parent and nested child transactions. Attaching any of them achieves the same result as attaching this transaction.

Throws:

java.lang.IllegalStateException - if transaction is attached to a different thread

Since:

1.2

attach

void attach()

Attaches this transaction to the current thread, if it has been detached. Attaching a transaction also attaches any parent and nested child transactions.

Throws:

java.lang.IllegalStateException - if current thread has a different transaction already attached

Since:

1.2

preCommit

boolean preCommit()
                  throws PersistException

Calling this method commits all nested child transactions, closes all scoped cursors, and locks out some interactions from other threads. The commit method must still be called to finish the commit. Most applications have no use for pre-commit and should only ever call commit.

The intent of this method is to complete as many operations as possible leading up to the actual commit. If pre-commit succeeds, then commit will most likely succeed as well. While in a pre-commit state, the transaction can still be used by the current thread. Calling pre-commit again ensures that child transactions and cursors are closed.

Returns:

false if transaction has exited

Throws:

PersistException