Package com.apple.foundationdb

## Interface Database

All Superinterfaces:
  `java.lang.AutoCloseable`, `ReadTransactionContext`, `TransactionContext`

    public interface Database
    extends java.lang.AutoCloseable, TransactionContext

A mutable, lexicographically ordered mapping from binary keys to binary values. `Transaction`s are used to manipulate data within a single `Database` -- multiple, concurrent `Transaction`s on a `Database` enforce ACID properties.
The simplest correct programs using FoundationDB will make use of the methods defined in the `TransactionContext` interface. When used on a `Database` these methods will call `Transaction#commit()` after user code has been executed. These methods will not return successfully until `commit()` has returned successfully.
Note: `Database` objects must be `closed` when no longer in use in order to free any associated resources.

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`void` `close()` Close the `Database` object and release any associated resources.
`default Transaction` `createTransaction()` Creates a `Transaction` that operates on this `Database`.
`Transaction` `createTransaction​(java.util.concurrent.Executor e)` Creates a `Transaction` that operates on this `Database` with the given `Executor` for asynchronous callbacks.
`Transaction` `createTransaction​(java.util.concurrent.Executor e, EventKeeper eventKeeper)` Creates a `Transaction` that operates on this `Database` with the given `Executor` for asynchronous callbacks.
`double` `getMainThreadBusyness()` Returns a value which indicates the saturation of the client Note: By default, this value is updated every second
`default Tenant` `openTenant​(byte[] tenantName)` Opens an existing tenant to be used for running transactions. Note: opening a tenant does not check its existence in the cluster.
`Tenant` `openTenant​(byte[] tenantName, java.util.concurrent.Executor e)` Opens an existing tenant to be used for running transactions.
`Tenant` `openTenant​(byte[] tenantName, java.util.concurrent.Executor e, EventKeeper eventKeeper)` Opens an existing tenant to be used for running transactions.
`Tenant` `openTenant​(Tuple tenantName)` Opens an existing tenant to be used for running transactions.
`Tenant` `openTenant​(Tuple tenantName, java.util.concurrent.Executor e)` Opens an existing tenant to be used for running transactions.
`Tenant` `openTenant​(Tuple tenantName, java.util.concurrent.Executor e, EventKeeper eventKeeper)` Opens an existing tenant to be used for running transactions.
`DatabaseOptions` `options()` Returns a set of options that can be set on a `Database`
`default <T> T` `read​(java.util.function.Function<? super ReadTransaction,​T> retryable)` Runs a read-only transactional function against this `Database` with retry logic.
`<T> T` `read​(java.util.function.Function<? super ReadTransaction,​T> retryable, java.util.concurrent.Executor e)` Runs a read-only transactional function against this `Database` with retry logic.
`default <T> java.util.concurrent.CompletableFuture<T>` `readAsync​(java.util.function.Function<? super ReadTransaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable)` Runs a read-only transactional function against this `Database` with retry logic.
`<T> java.util.concurrent.CompletableFuture<T>` `readAsync​(java.util.function.Function<? super ReadTransaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable, java.util.concurrent.Executor e)` Runs a read-only transactional function against this `Database` with retry logic.
`default <T> T` `run​(java.util.function.Function<? super Transaction,​T> retryable)` Runs a transactional function against this `Database` with retry logic.
`<T> T` `run​(java.util.function.Function<? super Transaction,​T> retryable, java.util.concurrent.Executor e)` Runs a transactional function against this `Database` with retry logic.
`default <T> java.util.concurrent.CompletableFuture<T>` `runAsync​(java.util.function.Function<? super Transaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable)` Runs a transactional function against this `Database` with retry logic.
`<T> java.util.concurrent.CompletableFuture<T>` `runAsync​(java.util.function.Function<? super Transaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable, java.util.concurrent.Executor e)` Runs a transactional function against this `Database` with retry logic.

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

`getExecutor`

### Method Detail

#### openTenant

    default Tenant openTenant​(byte[] tenantName)

Opens an existing tenant to be used for running transactions.
Note: opening a tenant does not check its existence in the cluster. If the tenant does not exist, attempts to read or write data with it will fail.

Parameters:
  `tenantName` - The name of the tenant to open.
Returns:
  a `Tenant` that can be used to create transactions that will operate in the tenant's key-space.

#### openTenant

    Tenant openTenant​(Tuple tenantName)

Opens an existing tenant to be used for running transactions. This is a convenience method that generates the tenant name by packing a `Tuple`.
Note: opening a tenant does not check its existence in the cluster. If the tenant does not exist, attempts to read or write data with it will fail.

Parameters:
  `tenantName` - The name of the tenant to open, as a Tuple.
Returns:
  a `Tenant` that can be used to create transactions that will operate in the tenant's key-space.

#### openTenant

    Tenant openTenant​(byte[] tenantName,
                      java.util.concurrent.Executor e)

Opens an existing tenant to be used for running transactions.

Parameters:
  `tenantName` - The name of the tenant to open.
  `e` - the `Executor` to use when executing asynchronous callbacks.
Returns:
  a `Tenant` that can be used to create transactions that will operate in the tenant's key-space.

#### openTenant

    Tenant openTenant​(Tuple tenantName,
                      java.util.concurrent.Executor e)

Opens an existing tenant to be used for running transactions. This is a convenience method that generates the tenant name by packing a `Tuple`.

Parameters:
  `tenantName` - The name of the tenant to open, as a Tuple.
  `e` - the `Executor` to use when executing asynchronous callbacks.
Returns:
  a `Tenant` that can be used to create transactions that will operate in the tenant's key-space.

#### openTenant

    Tenant openTenant​(byte[] tenantName,
                      java.util.concurrent.Executor e,
                      EventKeeper eventKeeper)

Opens an existing tenant to be used for running transactions.

Parameters:
  `tenantName` - The name of the tenant to open.
  `e` - the `Executor` to use when executing asynchronous callbacks.
  `eventKeeper` - the `EventKeeper` to use when tracking instrumented calls for the tenant's transactions.
Returns:
  a `Tenant` that can be used to create transactions that will operate in the tenant's key-space.

#### openTenant

    Tenant openTenant​(Tuple tenantName,
                      java.util.concurrent.Executor e,
                      EventKeeper eventKeeper)

Opens an existing tenant to be used for running transactions. This is a convenience method that generates the tenant name by packing a `Tuple`.

Parameters:
  `tenantName` - The name of the tenant to open, as a Tuple.
  `e` - the `Executor` to use when executing asynchronous callbacks.
  `eventKeeper` - the `EventKeeper` to use when tracking instrumented calls for the tenant's transactions.
Returns:
  a `Tenant` that can be used to create transactions that will operate in the tenant's key-space.

#### createTransaction

    default Transaction createTransaction()

Creates a `Transaction` that operates on this `Database`. Creating a transaction in this way does not associate it with a `Tenant`, and as a result the transaction will operate on the entire key-space for the database.
Note: Java transactions automatically set the `TransactionOptions.setUsedDuringCommitProtectionDisable()` option. This is because the Java bindings disallow use of `Transaction` objects after `Transaction.onError(java.lang.Throwable)` is called.
Note: Transactions created directly on a `Database` object cannot be used in a cluster that requires tenant-based access. To run transactions in those clusters, you must first open a tenant with `openTenant(byte[])`.

Returns:
  a newly created `Transaction` that reads from and writes to this `Database`.

#### createTransaction

    Transaction createTransaction​(java.util.concurrent.Executor e)

Creates a `Transaction` that operates on this `Database` with the given `Executor` for asynchronous callbacks.

Parameters:
  `e` - the `Executor` to use when executing asynchronous callbacks for the database
Returns:
  a newly created `Transaction` that reads from and writes to this `Database`.

#### createTransaction

    Transaction createTransaction​(java.util.concurrent.Executor e,
                                  EventKeeper eventKeeper)

Creates a `Transaction` that operates on this `Database` with the given `Executor` for asynchronous callbacks.

Parameters:
  `e` - the `Executor` to use when executing asynchronous callbacks for the database
  `eventKeeper` - the `EventKeeper` to use when tracking instrumented calls for the transaction.
Returns:
  a newly created `Transaction` that reads from and writes to this `Database`.

#### options

    DatabaseOptions options()

Returns a set of options that can be set on a `Database`

Returns:
  a set of database-specific options affecting this `Database`

#### getMainThreadBusyness

    double getMainThreadBusyness()

Returns a value which indicates the saturation of the client
Note: By default, this value is updated every second

Returns:
  a value where 0 indicates that the client is idle and 1 (or larger) indicates that the client is saturated.

#### read

    default <T> T read​(java.util.function.Function<? super ReadTransaction,​T> retryable)

Runs a read-only transactional function against this `Database` with retry logic. `apply(ReadTransaction)` will be called on the supplied `Function` until a non-retryable `FDBException` (or any `Throwable` other than an `FDBException`) is thrown. This call is blocking -- this method will not return until the `Function` has been called and completed without error.

Specified by:
  `read` in interface `ReadTransactionContext`
Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `Transaction` against this database
Returns:
  the result of the last run of `retryable`

#### read

    <T> T read​(java.util.function.Function<? super ReadTransaction,​T> retryable,
               java.util.concurrent.Executor e)

Runs a read-only transactional function against this `Database` with retry logic. Use this formulation of `read(Function)` if one wants to set a custom `Executor` for the transaction when run.

Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `Transaction` against this database
  `e` - the `Executor` to use for asynchronous callbacks
Returns:
  the result of the last run of `retryable`
See Also:
  `read(Function)`

#### readAsync

    default <T> java.util.concurrent.CompletableFuture<T> readAsync​(java.util.function.Function<? super ReadTransaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable)

Runs a read-only transactional function against this `Database` with retry logic. `apply(ReadTransaction)` will be called on the supplied `Function` until a non-retryable `FDBException` (or any `Throwable` other than an `FDBException`) is thrown. This call is non-blocking -- this method will return immediately and with a `CompletableFuture` that will be set when the `Function` has been called and completed without error.
Any errors encountered executing `retryable`, or received from the database, will be set on the returned `CompletableFuture`.

Specified by:
  `readAsync` in interface `ReadTransactionContext`
Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `ReadTransaction` against this database
Returns:
  a `CompletableFuture` that will be set to the value returned by the last call to `retryable`

#### readAsync

    <T> java.util.concurrent.CompletableFuture<T> readAsync​(java.util.function.Function<? super ReadTransaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable,
                                                            java.util.concurrent.Executor e)

Runs a read-only transactional function against this `Database` with retry logic. Use this version of `readAsync(Function)` if one wants to set a custom `Executor` for the transaction when run.

Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `ReadTransaction` against this database
  `e` - the `Executor` to use for asynchronous callbacks
Returns:
  a `CompletableFuture` that will be set to the value returned by the last call to `retryable`
See Also:
  `readAsync(Function)`

#### run

    default <T> T run​(java.util.function.Function<? super Transaction,​T> retryable)

Runs a transactional function against this `Database` with retry logic. `apply(Transaction)` will be called on the supplied `Function` until a non-retryable `FDBException` (or any `Throwable` other than an `FDBException`) is thrown or `commit()`, when called after `apply()`, returns success. This call is blocking -- this method will not return until `commit()` has been called and returned success.
As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, your transaction may be executed twice. For more information about how to reason about these situations see the FounationDB Developer Guide

Specified by:
  `run` in interface `TransactionContext`
Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `Transaction` against this database
Returns:
  the result of the last run of `retryable`

#### run

    <T> T run​(java.util.function.Function<? super Transaction,​T> retryable,
              java.util.concurrent.Executor e)

Runs a transactional function against this `Database` with retry logic. Use this formulation of `run(Function)` if one would like to set a custom `Executor` for the transaction when run.

Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `Transaction` against this database
  `e` - the `Executor` to use for asynchronous callbacks
Returns:
  the result of the last run of `retryable`

#### runAsync

    default <T> java.util.concurrent.CompletableFuture<T> runAsync​(java.util.function.Function<? super Transaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable)

Runs a transactional function against this `Database` with retry logic. `apply(Transaction)` will be called on the supplied `Function` until a non-retryable `FDBException` (or any `Throwable` other than an `FDBException`) is thrown or `commit()`, when called after `apply()`, returns success. This call is non-blocking -- this method will return immediately and with a `CompletableFuture` that will be set when `commit()` has been called and returned success.
As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, your transaction may be executed twice. For more information about how to reason about these situations see the FounationDB Developer Guide
Any errors encountered executing `retryable`, or received from the database, will be set on the returned `CompletableFuture`.

Specified by:
  `runAsync` in interface `TransactionContext`
Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `Transaction` against this database
Returns:
  a `CompletableFuture` that will be set to the value returned by the last call to `retryable`

#### runAsync

    <T> java.util.concurrent.CompletableFuture<T> runAsync​(java.util.function.Function<? super Transaction,​? extends java.util.concurrent.CompletableFuture<T>> retryable,
                                                           java.util.concurrent.Executor e)

Runs a transactional function against this `Database` with retry logic. Use this formulation of the non-blocking `runAsync(Function)` if one wants to set a custom `Executor` for the transaction when run.

Type Parameters:
  `T` - the return type of `retryable`
Parameters:
  `retryable` - the block of logic to execute in a `Transaction` against this database
  `e` - the `Executor` to use for asynchronous callbacks
Returns:
  a `CompletableFuture` that will be set to the value returned by the last call to `retryable`
See Also:
  `run(Function)`

#### close

    void close()

Close the `Database` object and release any associated resources. This must be called at least once after the `Database` object is no longer in use. This can be called multiple times, but care should be taken that it is not in use in another thread at the time of the call.

Specified by:
  `close` in interface `java.lang.AutoCloseable`