Transaction (FoundationDB Java Client API)

All Superinterfaces:

Cancellable, Disposable, ReadTransaction, ReadTransactionContext, TransactionContext
```
public interface Transaction
extends Cancellable, Disposable, ReadTransaction, TransactionContext
```
A Transaction represents a FoundationDB database transaction. All operations on FoundationDB take place, explicitly or implicitly, through a Transaction.

In FoundationDB, a transaction is a mutable snapshot of a database. All read and write operations on a transaction see and modify an otherwise-unchanging version of the database and only change the underlying database if and when the transaction is committed. Read operations do see the effects of previous write operations on the same transaction. Committing a transaction usually succeeds in the absence of conflicts.

Transactions group operations into a unit with the properties of atomicity, isolation, and durability. Transactions also provide the ability to maintain an application's invariants or integrity constraints, supporting the property of consistency. Together these properties are known as ACID.

Transactions are also causally consistent: once a transaction has been successfully committed, all subsequently created transactions will see the modifications made by it. The most convenient way for a developer to manage the lifecycle and retrying of a Transaction is to use Database.run(com.foundationdb.async.Function). Otherwise, the client must have retry logic for fatal failures, failures to commit, and other transient errors.

Keys and values in FoundationDB are byte arrays. To encode other data types, see the Tuple API and tuple layer documentation.

When used as a TransactionContext, the methods run() and runAsync() on a Transaction will simply attempt the operations without any retry loop.

Note: Client must call commit() and wait on the result on all transactions, even ones that only read. This is done automatically when using the retry loops from Database.run(Function). This is because outstanding reads originating from a Transaction will be cancelled when a Transaction is garbage collected. Since the garbage collector reserves the right to collect an in-scope object if it determines that there are no subsequent references it it, this can happen in seemingly innocuous situations. Futures returned from commit() will block until all reads are complete, thereby saving the calling code from this potentially confusing situation.

Note: All keys with a first byte of 0xff are reserved for internal use.

Field Summary
- Fields inherited from interface com.foundationdb.ReadTransaction
  ROW_LIMIT_UNLIMITED

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addReadConflictKey(byte[] key)` Adds a key to the transaction's read conflict ranges as if you had read the key.
`void`	`addReadConflictRange(byte[] keyBegin, byte[] keyEnd)` Adds a range of keys to the transaction's read conflict ranges as if you had read the range.
`void`	`addWriteConflictKey(byte[] key)` Adds a key to the transaction's write conflict ranges as if you had written the key.
`void`	`addWriteConflictRange(byte[] keyBegin, byte[] keyEnd)` Adds a range of keys to the transaction's write conflict ranges as if you had cleared the range.
`void`	`cancel()` Cancels the `Transaction`.
`void`	`clear(byte[] key)` Clears a given key from the database.
`void`	`clear(byte[] beginKey, byte[] endKey)` Clears a range of keys in the database.
`void`	`clear(Range range)` Clears a range of keys in the database.
`void`	`clearRangeStartsWith(byte[] prefix)` Deprecated.
`Future<Void>`	`commit()` Commit this `Transaction`.
`Long`	`getCommittedVersion()` Gets the version number at which a successful commit modified the database.
`Database`	`getDatabase()` Returns the `Database` that this `Transaction` is interacting with.
`void`	`mutate(MutationType optype, byte[] key, byte[] param)` An atomic operation is a single database command that carries out several logical steps: reading the value of a key, performing a transformation on that value, and writing the result.
`PartialFuture<Void>`	`onError(Exception e)` Convenience method for compatibility with code that does not want to do type-based dispatching of errors.
`Future<Void>`	`onError(RuntimeException e)` Resets a transaction and returns a delayed signal for error recovery.
`TransactionOptions`	`options()` Returns a set of options that can be set on a `Transaction`
`void`	`reset()` Resets a `Transaction` to its initial state after creation.
`<T> T`	`run(Function<? super Transaction,T> retryable)` Run a function once against this `Transaction`.
`<T> T`	`run(PartialFunction<? super Transaction,T> retryable)` Run a function once against this `Transaction`.
`<T> Future<T>`	`runAsync(Function<? super Transaction,Future<T>> retryable)` Run a function once against this `Transaction`.
`<T> PartialFuture<T>`	`runAsync(PartialFunction<? super Transaction,? extends PartialFuture<T>> retryable)` Run a function once against this `Transaction`.
`void`	`set(byte[] key, byte[] value)` Sets the value for a given key.
`void`	`setReadVersion(long version)` Directly sets the version of the database at which to execute reads.
`ReadTransaction`	`snapshot()` Return special-purpose, read-only view of the database.
`Future<Void>`	`watch(byte[] key)` Creates a watch that will become ready when it reports a change to the value of the specified key. A watch's behavior is relative to the transaction that created it.

Methods inherited from interface com.foundationdb.Disposable
dispose

Methods inherited from interface com.foundationdb.ReadTransaction
get, getKey, getRange, getRange, getRange, getRange, getRange, getRange, getRange, getRange, getRange, getRange, getRange, getRange, getReadVersion

Methods inherited from interface com.foundationdb.ReadTransactionContext
read, read, readAsync, readAsync

- Method Detail
  - snapshot
```
ReadTransaction snapshot()
```
    Return special-purpose, read-only view of the database. Reads done through this interface are known as "snapshot reads". Snapshot reads selectively relax FoundationDB's isolation property, reducing Transaction conflicts but making reasoning about concurrency harder.
    
    For more information about how to use snapshot reads correctly, see Using snapshot reads.
  - setReadVersion
```
void setReadVersion(long version)
```
    Directly sets the version of the database at which to execute reads. The normal operation of a transaction is to determine an appropriately recent version; this call overrides that behavior. If the version is set too far in the past, past_version errors will be thrown from read operations. Infrequently used.
    
    Parameters:
    version - the version at which to read from the database
  - addReadConflictRange
```
void addReadConflictRange(byte[] keyBegin,
                        byte[] keyEnd)
```
    Adds a range of keys to the transaction's read conflict ranges as if you had read the range. As a result, other transactions that write a key in this range could cause the transaction to fail with a conflict.
    
    Parameters:
    keyBegin - the first key in the range (inclusive)
    keyEnd - the ending key for the range (exclusive)
  - addReadConflictKey
```
void addReadConflictKey(byte[] key)
```
    Adds a key to the transaction's read conflict ranges as if you had read the key. As a result, other transactions that concurrently write this key could cause the transaction to fail with a conflict.
    
    Parameters:
    key - the key to be added to the range
  - addWriteConflictRange
```
void addWriteConflictRange(byte[] keyBegin,
                         byte[] keyEnd)
```
    Adds a range of keys to the transaction's write conflict ranges as if you had cleared the range. As a result, other transactions that concurrently read a key in this range could fail with a conflict.
    
    Parameters:
    keyBegin - the first key in the range (inclusive)
    keyEnd - the ending key for the range (exclusive)
  - addWriteConflictKey
```
void addWriteConflictKey(byte[] key)
```
    Adds a key to the transaction's write conflict ranges as if you had written the key. As a result, other transactions that concurrently read this key could fail with a conflict.
    
    Parameters:
    key - the key to be added to the range
  - set
```
void set(byte[] key,
       byte[] value)
```
    Sets the value for a given key. This will not affect the database until commit() is called.
    
    Parameters:
    key - the key whose value is to be set
    value - the value to set in the database
    
    Throws:
    
    IllegalArgumentException
    
    FDBException
  - clear
```
void clear(byte[] key)
```
    Clears a given key from the database. This will not affect the database until commit() is called.
    
    Parameters:
    key - the key whose value is to be cleared
    
    Throws:
    
    IllegalArgumentException
    
    FDBException
  - clear
```
void clear(byte[] beginKey,
         byte[] endKey)
```
    Clears a range of keys in the database. The upper bound of the range is exclusive; that is, the key (if one exists) that is specified as the end of the range will NOT be cleared as part of this operation. Range clears are efficient with FoundationDB -- clearing large amounts of data will be fast. This will not affect the database until commit() is called.
    
    Parameters:
    beginKey - the first clear
    endKey - the key one past the last key to clear
    
    Throws:
    
    IllegalArgumentException
    
    FDBException
  - clear
```
void clear(Range range)
```
    Clears a range of keys in the database. The upper bound of the range is exclusive; that is, the key (if one exists) that is specified as the end of the range will NOT be cleared as part of this operation. Range clears are efficient with FoundationDB -- clearing large amounts of data will be fast. This will not affect the database until commit() is called.
    
    Parameters:
    range - the range of keys to clear
    
    Throws:
    
    FDBException
  - clearRangeStartsWith
```
@Deprecated
void clearRangeStartsWith(byte[] prefix)
```
    Deprecated.
    
    Replace with calls to clear(Range) with a parameter from a call to Range.startsWith(byte[]).
    
    Parameters:
    prefix - the starting bytes from the keys to be cleared.
    
    Throws:
    
    FDBException
  - mutate
```
void mutate(MutationType optype,
          byte[] key,
          byte[] param)
```
    An atomic operation is a single database command that carries out several logical steps: reading the value of a key, performing a transformation on that value, and writing the result. Different atomic operations perform different transformations. Like other database operations, an atomic operation is used within a transaction.
    
    Atomic operations do not expose the current value of the key to the client but simply send the database the transformation to apply. In regard to conflict checking, an atomic operation is equivalent to a write without a read. It can only cause other transactions performing reads of the key to conflict.
    
    By combining these logical steps into a single, read-free operation, FoundationDB can guarantee that the transaction will not conflict due to the operation. This makes atomic operations ideal for operating on keys that are frequently modified. A common example is the use of a key-value pair as a counter.
    
    Note: If a transaction uses both an atomic operation and a serializable read on the same key, the benefits of using the atomic operation (for both conflict checking and performance) are lost. The behavior of each MutationType is documented at its definition.
    
    Parameters:
    optype - the operation to perform
    key - the target of the operation
    param - the value with which to modify the key
  - options
```
TransactionOptions options()
```
    Returns a set of options that can be set on a Transaction
    
    Returns:
    a set of transaction-specific options affecting this Transaction
  - commit
```
Future<Void> commit()
```
    Commit this Transaction. See notes in class description. Consider using Database's run() calls for managing transactional access to FoundationDB.
    
    Returns:
    a Future that, when set without error, guarantees the Transaction's modifications committed durably to the database. If the commit failed, it will throw an FDBException.
    
    As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, an FDBException will be thrown with error code commit_unknown_result (1021). The onError(java.lang.RuntimeException) function regards this exception as a retryable one, so retry loops that don't specifically detect commit_unknown_result could end up executing a transaction twice. For more information, see the FoundationDB Developer Guide documentation. If any operation is performed on a transaction after a commit has been issued but before it has returned, both the commit and the operation will throw an error code used_during_commit(2017). In this case, all subsequent operations on this transaction will throw this error until reset() is called.
  - getCommittedVersion
```
Long getCommittedVersion()
```
    Gets the version number at which a successful commit modified the database. This must be called only after the successful (non-error) completion of a call to commit() on this Transaction, or the behavior is undefined. Read-only transactions do not modify the database when committed and will have a committed version of -1. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.
    
    Returns:
    the database version at which the commit succeeded
  - onError
```
Future<Void> onError(RuntimeException e)
```
    Resets a transaction and returns a delayed signal for error recovery. If the error encountered by the Transaction could not be recovered from, the returned Future will be set to an error state.
    
    Parameters:
    e - the error caught while executing get()s and set()s on this Transaction
    
    Returns:
    a Future to be set as a signal for retrying the Transaction
  - onError
```
PartialFuture<Void> onError(Exception e)
```
    Convenience method for compatibility with code that does not want to do type-based dispatching of errors. Since all retryable errors are subclasses of RuntimeException, this version of onError() simply returns a PartialFuture set to the supplied error.
    
    Parameters:
    e - the error caught while executing get()s and set()s on this Transaction
    
    Returns:
    a Future to be set as a signal for retrying the Transaction
  - reset
```
void reset()
```
    Resets a Transaction to its initial state after creation. This clears all information about mutations, conflict information built from gets, and the read version. This does not clear any options set on this Transaction via a TransactionOptions object.
  - cancel
```
void cancel()
```
    Cancels the Transaction. All pending and any future uses of the Transaction will throw an RuntimeException. This Transaction can be used again after reset() is called.
    
    Specified by:
    
    cancel in interface Cancellable
  - watch
```
Future<Void> watch(byte[] key)
                   throws FDBException
```
    Creates a watch that will become ready when it reports a change to the value of the specified key.
    
    A watch's behavior is relative to the transaction that created it. A watch will report a change in relation to the key's value as readable by that transaction. The initial value used for comparison is either that of the transaction's read version or the value as modified by the transaction itself prior to the creation of the watch. If the value changes and then changes back to its initial value, the watch might not report the change.
    
    Until the transaction that created it has been committed, a watch will not report changes made by other transactions. In contrast, a watch will immediately report changes made by the transaction itself. Watches cannot be created if the transaction has set TransactionOptions.setReadYourWritesDisable(), and an attempt to do so will raise a watches_disabled exception.
    
    If the transaction used to create a watch encounters an exception during commit, then the watch will be set with that exception. A transaction whose commit result is unknown will set all of its watches with the commit_unknown_result exception. If an uncommitted transaction is reset or destroyed, then any watches it created will be set with the transaction_cancelled exception.
    
    By default, each database connection can have no more than 10,000 watches that have not yet reported a change. When this number is exceeded, an attempt to create a watch will raise a too_many_watches exception. Because a watch outlives the transaction that creates it, any watch that is no longer needed should be cancelled.
    
    NOTE: calling code must call commit() for the watch to be registered with the database.
    
    Parameters:
    key - the key to watch for changes in value
    
    Returns:
    a Future that will become ready when the value changes
    
    Throws:
    
    FDBException - if too many watches have been created on this database. The limit defaults to 10,000 and can be modified with a call to DatabaseOptions.setMaxWatches(long).
  - getDatabase
```
Database getDatabase()
```
    Returns the Database that this Transaction is interacting with.
    
    Returns:
    the Database object
  - run
```
<T> T run(Function<? super Transaction,T> retryable)
```
    Run a function once against this Transaction. This call blocks while user code is executing, returning the result of that code on completion.
    
    Specified by:
    
    run in interface TransactionContext
    
    Parameters:
    retryable - the block of logic to execute against a Transaction in this context
    
    Returns:
    the return value of retryable
  - run
```
<T> T run(PartialFunction<? super Transaction,T> retryable)
      throws Exception
```
    Run a function once against this Transaction. This call blocks while user code is executing, returning the result of that code on completion.
    
    Specified by:
    
    run in interface TransactionContext
    
    Parameters:
    retryable - the block of logic to execute against a Transaction in this context
    
    Returns:
    the return value of retryable
    
    Throws:
    
    Exception - if an error is encountered during execution
    See Also:
    TransactionContext.run(Function)
  - runAsync
```
<T> Future<T> runAsync(Function<? super Transaction,Future<T>> retryable)
```
    Run a function once against this Transaction. This call returns immediately with a Future handle to the result.
    
    Specified by:
    
    runAsync in interface TransactionContext
    
    Parameters:
    retryable - the block of logic to execute against a Transaction in this context
    
    Returns:
    a Future that will be set to the return value of retryable
  - runAsync
```
<T> PartialFuture<T> runAsync(PartialFunction<? super Transaction,? extends PartialFuture<T>> retryable)
```
    Run a function once against this Transaction. This call returns immediately with a PartialFuture handle to the result. Use this formulation of runAsync(Function) if user code throws a checked exception.
    
    Specified by:
    
    runAsync in interface TransactionContext
    
    Parameters:
    retryable - the block of logic to execute against a Transaction in this context
    
    Returns:
    a PartialFuture that will be set to the return value of retryable

Interface Transaction

Field Summary

Fields inherited from interface com.foundationdb.ReadTransaction

Method Summary

Methods inherited from interface com.foundationdb.Disposable

Methods inherited from interface com.foundationdb.ReadTransaction

Methods inherited from interface com.foundationdb.ReadTransactionContext

Method Detail

snapshot

setReadVersion

addReadConflictRange

addReadConflictKey

addWriteConflictRange

addWriteConflictKey

set

clear

clear

clear

clearRangeStartsWith

mutate

options

commit

getCommittedVersion

onError

onError

reset

cancel

watch

getDatabase

run

run

runAsync

runAsync