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. Transactions are used to manipulate data within a single Database -- multiple, concurrent Transactions 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

Modifier and Type	Method and Description
void	close() Close the Database object and release any associated resources.
default Transaction	createTransaction() Creates a Transaction that operates on this Database. Note: Java transactions automatically set the TransactionOptions.setUsedDuringCommitProtectionDisable() option.
Transaction	createTransaction(java.util.concurrent.Executor e) Creates a Transaction that operates on this Database with the given Executor for asynchronous callbacks.
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

createTransaction

default Transaction createTransaction()

Creates a Transaction that operates on this 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.

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.

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

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