com.apple.foundationdb

## Interface ReadTransaction

All Superinterfaces:
  ReadTransactionContext

All Known Subinterfaces:
  Transaction

    public interface ReadTransaction
    extends ReadTransactionContext

A read-only subset of a FoundationDB `Transaction`. This is the interface that `Transaction`'s `snapshot` presents.
Note: Client must call `Transaction.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 explained more in the intro to `Transaction`.

See Also:
  `Transaction`

### Field Summary

Fields
`static int` `ROW_LIMIT_UNLIMITED` When passed to a `getRange()` call that takes a `limit` parameter, indicates that the query should return unlimited rows.

### Method Summary

All Methods Instance Methods Abstract Methods
`java.util.concurrent.CompletableFuture<byte[]>` `get(byte[] key)` Gets a value from the database.
`java.util.concurrent.CompletableFuture<byte[]>` `getKey(KeySelector selector)` Returns the key referenced by the specified `KeySelector`.
`AsyncIterable<KeyValue>` `getRange(byte[] begin, byte[] end)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(byte[] begin, byte[] end, int limit)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(byte[] begin, byte[] end, int limit, boolean reverse)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(byte[] begin, byte[] end, int limit, boolean reverse, StreamingMode mode)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(KeySelector begin, KeySelector end)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(KeySelector begin, KeySelector end, int limit)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(KeySelector begin, KeySelector end, int limit, boolean reverse)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(KeySelector begin, KeySelector end, int limit, boolean reverse, StreamingMode mode)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(Range range)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(Range range, int limit)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(Range range, int limit, boolean reverse)` Gets an ordered range of keys and values from the database.
`AsyncIterable<KeyValue>` `getRange(Range range, int limit, boolean reverse, StreamingMode mode)` Gets an ordered range of keys and values from the database.
`java.util.concurrent.CompletableFuture<java.lang.Long>` `getReadVersion()` Gets the version at which the reads for this `Transaction` will access the database.
`TransactionOptions` `options()` Returns a set of options that can be set on a `Transaction`

### Methods inherited from interface com.apple.foundationdb.ReadTransactionContext

`getExecutor, read, readAsync`

### Field Detail

#### ROW_LIMIT_UNLIMITED

    static final int ROW_LIMIT_UNLIMITED

When passed to a `getRange()` call that takes a `limit` parameter, indicates that the query should return unlimited rows.

See Also:
  Constant Field Values

### Method Detail

#### getReadVersion

    java.util.concurrent.CompletableFuture<java.lang.Long> getReadVersion()

Gets the version at which the reads for this `Transaction` will access the database.

Returns:
  the version for database reads

#### get

    java.util.concurrent.CompletableFuture<byte[]> get(byte[] key)

Gets a value from the database. The call will return `null` if the key is not present in the database.

Parameters:
  `key` - the key whose value to fetch from the database
Returns:
  a `CompletableFuture` which will be set to the value corresponding to the key or to null if the key does not exist.

#### getKey

    java.util.concurrent.CompletableFuture<byte[]> getKey(KeySelector selector)

Returns the key referenced by the specified `KeySelector`. By default, the key is cached for the duration of the transaction, providing a potential performance benefit. However, the value of the key is also retrieved, using network bandwidth. Invoking `setReadYourWritesDisable` will avoid both the caching and the increased network bandwidth.

Parameters:
  `selector` - the relative key location to resolve
Returns:
  a `CompletableFuture` which will be set to an absolute database key
See Also:
  `KeySelector`

#### getRange

    AsyncIterable<KeyValue> getRange(KeySelector begin,
                                     KeySelector end)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `KeySelector`s, with the begin `KeySelector` inclusive and the end `KeySelector` exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(KeySelector begin,
                                     KeySelector end,
                                     int limit)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `KeySelector`s, with the begin `KeySelector` inclusive and the end `KeySelector` exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results.
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(KeySelector begin,
                                     KeySelector end,
                                     int limit,
                                     boolean reverse)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `KeySelector`s, with the begin `KeySelector` inclusive and the end `KeySelector` exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results. If `reverse` is `true` rows will be limited starting at the end of the range.
  `reverse` - return results starting at the end of the range in reverse order
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(KeySelector begin,
                                     KeySelector end,
                                     int limit,
                                     boolean reverse,
                                     StreamingMode mode)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `KeySelector`s, with the begin `KeySelector` inclusive and the end `KeySelector` exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results. If `reverse` is `true` rows will be limited starting at the end of the range.
  `reverse` - return results starting at the end of the range in reverse order
  `mode` - provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(byte[] begin,
                                     byte[] end)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(byte[] begin,
                                     byte[] end,
                                     int limit)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results.
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(byte[] begin,
                                     byte[] end,
                                     int limit,
                                     boolean reverse)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results. If `reverse` is `true` rows will be limited starting at the end of the range.
  `reverse` - return results starting at the end of the range in reverse order
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(byte[] begin,
                                     byte[] end,
                                     int limit,
                                     boolean reverse,
                                     StreamingMode mode)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive.

Parameters:
  `begin` - the beginning of the range (inclusive)
  `end` - the end of the range (exclusive)
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results. If `reverse` is `true` rows will be limited starting at the end of the range.
  `reverse` - return results starting at the end of the range in reverse order
  `mode` - provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(Range range)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive. `Range`s are returned from calls to `Tuple.range()` and `Range.startsWith(byte[])`.
Note: users of older version of the API should replace old calls to `getRangeStartsWith( k )` with `getRange(Range.startsWith( k ))`

Parameters:
  `range` - the range of keys to return
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(Range range,
                                     int limit)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive. `Range`s are returned from calls to `Tuple.range()` and `Range.startsWith(byte[])`.
Note: users of older version of the API should replace old calls to `getRangeStartsWith( k )` with `getRange(Range.startsWith( k ))`

Parameters:
  `range` - the range of keys to return
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results.
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(Range range,
                                     int limit,
                                     boolean reverse)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive. `Range`s are returned from calls to `Tuple.range()` and `Range.startsWith(byte[])`.
Note: users of older version of the API should replace old calls to `getRangeStartsWith( k )` with `getRange(Range.startsWith( k ))`

Parameters:
  `range` - the range of keys to return
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results. If `reverse` is `true` rows will be limited starting at the end of the range.
  `reverse` - return results starting at the end of the range in reverse order
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### getRange

    AsyncIterable<KeyValue> getRange(Range range,
                                     int limit,
                                     boolean reverse,
                                     StreamingMode mode)

Gets an ordered range of keys and values from the database. The begin and end keys are specified by `byte[]` arrays, with the begin key inclusive and the end key exclusive. `Range`s are returned from calls to `Tuple.range()` and `Range.startsWith(byte[])`.
Note: users of older version of the API should replace old calls to `getRangeStartsWith( k )` with `getRange(Range.startsWith( k ))`

Parameters:
  `range` - the range of keys to return
  `limit` - the maximum number of results to return. Limits results to the first keys in the range. Pass `ROW_LIMIT_UNLIMITED` if this query should not limit the number of results. If `reverse` is `true` rows will be limited starting at the end of the range.
  `reverse` - return results starting at the end of the range in reverse order
  `mode` - provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.
Returns:
  a handle to access the results of the asynchronous call
See Also:
  `KeySelector`, `AsyncIterator`

#### 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`