com.apple.foundationdb

Class FDB

java.lang.Object

com.apple.foundationdb.FDB

public class FDB
extends java.lang.Object

The starting point for accessing FoundationDB.

Setting API version

The FoundationDB API is accessed with a call to selectAPIVersion(int). This call is required before using any other part of the API. The call allows an error to be thrown at this point to prevent client code from accessing a later library with incorrect assumptions from the current version. The API version documented here is version 630.

FoundationDB encapsulates multiple versions of its interface by requiring the client to explicitly specify the version of the API it uses. The purpose of this design is to allow you to upgrade the server, client libraries, or bindings without having to modify client code. The client libraries support all previous versions of the API. The API version specified by the client is used to control the behavior of the binding. You can therefore upgrade to more recent packages (and thus receive various improvements) without having to change your code.

Warning: When using the multi-version client API, setting an API version that is not supported by a particular client library will prevent that client from being used to connect to the cluster. In particular, you should not advance the API version of your application after upgrading your client until the cluster has also been upgraded.

Getting a database

Once the API version has been set, the easiest way to get a Database object to use is to call open().

Client networking

The network is started either implicitly with a call to a variant of open() or started explicitly with a call to startNetwork().

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.concurrent.ExecutorService	DEFAULT_EXECUTOR

Method Summary

Modifier and Type	Method and Description
Cluster	createCluster() Deprecated. Use open() instead.
Cluster	createCluster(java.lang.String clusterFilePath) Deprecated. Use open(String) instead.
Cluster	createCluster(java.lang.String clusterFilePath, java.util.concurrent.Executor e) Deprecated. Use open(String, Executor) instead.
void	disableShutdownHook() Disables shutdown hook that stops network thread upon process shutdown.
void	enableDirectBufferQuery(boolean enabled) Enables or disables use of DirectByteBuffers for getRange() queries.
int	getAPIVersion() Returns the API version that was selected by the selectAPIVersion() call.
static FDB	instance() Return the instance of the FDB API singleton.
static boolean	isAPIVersionSelected() Determines if the API version has already been selected.
boolean	isDirectBufferQueriesEnabled() Determines whether getRange() queries can use DirectByteBuffer from DirectBufferPool to copy results.
Database	open() Initializes networking if required and connects to the cluster specified by the default fdb.cluster file. A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.
Database	open(java.lang.String clusterFilePath) Initializes networking if required and connects to the cluster specified by clusterFilePath. A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.
Database	open(java.lang.String clusterFilePath, EventKeeper eventKeeper) Initializes networking if required and connects to the cluster specified by clusterFilePath. A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.
Database	open(java.lang.String clusterFilePath, java.util.concurrent.Executor e) Initializes networking if required and connects to the cluster specified by clusterFilePath. A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.
Database	open(java.lang.String clusterFilePath, java.util.concurrent.Executor e, EventKeeper eventKeeper) Initializes networking if required and connects to the cluster specified by clusterFilePath. A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.
NetworkOptions	options() Returns a set of options that can be set on a the FoundationDB API.
void	resizeDirectBufferPool(int poolSize, int bufferSize) Resizes the DirectBufferPool with given parameters, which is used by getRange() requests.
static FDB	selectAPIVersion(int version) Select the version for the client API.
void	setUnclosedWarning(boolean warnOnUnclosed) Enables or disables the stderr warning that is printed whenever an object with FoundationDB native resources is garbage collected without being closed.
void	startNetwork() Initializes networking.
void	startNetwork(java.util.concurrent.Executor e) Initializes networking.
void	stopNetwork() Stops the FoundationDB networking engine.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_EXECUTOR

public static final java.util.concurrent.ExecutorService DEFAULT_EXECUTOR

Method Detail

options

public NetworkOptions options()

Returns a set of options that can be set on a the FoundationDB API. Generally, these options to the top level of the API affect the networking engine and therefore must be set before the network engine is started. The network is started by calls to startNetwork() or implicitly by a call to open() and and its variants.

Returns:

a set of options affecting this instance of the FoundationDB API

isAPIVersionSelected

public static boolean isAPIVersionSelected()

Determines if the API version has already been selected. That is, this will return true if the user has already called selectAPIVersion() and that call has completed successfully.

Returns:

true if an API version has been selected and false otherwise

instance

public static FDB instance()
                    throws FDBException

Return the instance of the FDB API singleton. This method will always return a non-null value for the singleton, but if the selectAPIVersion() method has not yet been called, it will throw an FDBException indicating that an API version has not yet been set.

Returns:

the FoundationDB API object

Throws:

FDBException - if selectAPIVersion() has not been called

selectAPIVersion

public static FDB selectAPIVersion(int version)
                            throws FDBException

Select the version for the client API. An exception will be thrown if the requested version is not supported by this implementation of the API. As only one version can be selected for the lifetime of the JVM, the result of a successful call to this method is always the same instance of a FDB object.

Warning: When using the multi-version client API, setting an API version that is not supported by a particular client library will prevent that client from being used to connect to the cluster. In particular, you should not advance the API version of your application after upgrading your client until the cluster has also been upgraded.

Parameters:

version - the API version required

Returns:

the FoundationDB API object

Throws:

FDBException

disableShutdownHook

public void disableShutdownHook()

Disables shutdown hook that stops network thread upon process shutdown. This is useful if you need to run your own shutdown hook that uses the FDB instance and you need to avoid race conditions with the default shutdown hook. Replacement shutdown hook should stop the network thread manually by calling stopNetwork().

setUnclosedWarning

public void setUnclosedWarning(boolean warnOnUnclosed)

Enables or disables the stderr warning that is printed whenever an object with FoundationDB native resources is garbage collected without being closed. By default, this feature is enabled.

Parameters:

warnOnUnclosed - Whether the warning should be printed for unclosed objects

getAPIVersion

public int getAPIVersion()

Returns the API version that was selected by the selectAPIVersion() call. This can be used to guard different parts of client code against different versions of the FoundationDB API to allow for libraries using FoundationDB to be compatible across several versions.

Returns:

the FoundationDB API version that has been loaded

enableDirectBufferQuery

public void enableDirectBufferQuery(boolean enabled)

Enables or disables use of DirectByteBuffers for getRange() queries.

Parameters:

enabled - Whether DirectByteBuffer should be used for getRange() queries.

isDirectBufferQueriesEnabled

public boolean isDirectBufferQueriesEnabled()

Determines whether getRange() queries can use DirectByteBuffer from DirectBufferPool to copy results.

Returns:

true if direct buffer queries have been enabled and false otherwise

resizeDirectBufferPool

public void resizeDirectBufferPool(int poolSize,
                                   int bufferSize)

Resizes the DirectBufferPool with given parameters, which is used by getRange() requests.

Parameters:

poolSize - Number of buffers in pool

bufferSize - Size of each buffer in bytes

createCluster

@Deprecated
public Cluster createCluster()
                                  throws java.lang.IllegalStateException,
                                         FDBException

Deprecated. Use open() instead.

Connects to the cluster specified by the default fdb.cluster file. If the FoundationDB network has not been started, it will be started in the course of this call as if startNetwork() had been called.

Returns:

a CompletableFuture that will be set to a FoundationDB Cluster.

Throws:

FDBException - on errors encountered starting the FoundationDB networking engine

java.lang.IllegalStateException - if the network had been previously stopped

createCluster

@Deprecated
public Cluster createCluster(java.lang.String clusterFilePath)
                                  throws java.lang.IllegalStateException,
                                         FDBException

Deprecated. Use open(String) instead.

Connects to the cluster specified by clusterFilePath. If the FoundationDB network has not been started, it will be started in the course of this call as if startNetwork() had been called.

Parameters:

clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.

Returns:

a CompletableFuture that will be set to a FoundationDB Cluster.

Throws:

FDBException - on errors encountered starting the FoundationDB networking engine

java.lang.IllegalStateException - if the network had been previously stopped

createCluster

@Deprecated
public Cluster createCluster(java.lang.String clusterFilePath,
                                         java.util.concurrent.Executor e)
                                  throws FDBException,
                                         java.lang.IllegalStateException

Deprecated. Use open(String, Executor) instead.

Connects to the cluster specified by clusterFilePath. If the FoundationDB network has not been started, it will be started in the course of this call. The supplied Executor will be used as the default for the execution of all callbacks that are produced from using the resulting Cluster.

Parameters:

clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.

e - used to run the FDB network thread

Returns:

a CompletableFuture that will be set to a FoundationDB Cluster.

Throws:

FDBException - on errors encountered starting the FoundationDB networking engine

java.lang.IllegalStateException - if the network had been previously stopped

open

public Database open()
              throws FDBException

Initializes networking if required and connects to the cluster specified by the default fdb.cluster file.

A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the multi-version client API must be used.

Returns:

a CompletableFuture that will be set to a FoundationDB Database

Throws:

FDBException

open

public Database open(java.lang.String clusterFilePath)
              throws FDBException

Initializes networking if required and connects to the cluster specified by clusterFilePath.

A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the multi-version client API must be used.

Parameters:

clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.

Returns:

a CompletableFuture that will be set to a FoundationDB Database

Throws:

FDBException

open

public Database open(java.lang.String clusterFilePath,
                     EventKeeper eventKeeper)
              throws FDBException

Initializes networking if required and connects to the cluster specified by clusterFilePath.

A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the multi-version client API must be used.

Parameters:

clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.

eventKeeper - the EventKeeper to use for instrumentation calls, or null if no instrumentation is desired.

Returns:

a CompletableFuture that will be set to a FoundationDB Database

Throws:

FDBException

open

public Database open(java.lang.String clusterFilePath,
                     java.util.concurrent.Executor e)
              throws FDBException

Initializes networking if required and connects to the cluster specified by clusterFilePath.

A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the multi-version client API must be used.

Parameters:

clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.

e - the Executor to use to execute asynchronous callbacks

Returns:

a CompletableFuture that will be set to a FoundationDB Database

Throws:

FDBException

open

public Database open(java.lang.String clusterFilePath,
                     java.util.concurrent.Executor e,
                     EventKeeper eventKeeper)
              throws FDBException

Initializes networking if required and connects to the cluster specified by clusterFilePath.

A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the multi-version client API must be used.

Parameters:

clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.

e - the Executor to use to execute asynchronous callbacks

eventKeeper - the EventKeeper to use to record instrumentation metrics, or null if no instrumentation is desired.

Returns:

a CompletableFuture that will be set to a FoundationDB Database

Throws:

FDBException

startNetwork

public void startNetwork()
                  throws FDBException,
                         java.lang.IllegalStateException

Initializes networking. Can only be called once. This version of startNetwork() will create a new thread and execute the networking event loop on that thread. This method is called upon Database creation by default if the network has not yet been started. If one wishes to control what thread the network runs on, one should use the version of startNetwork() that takes an Executor.

Configuration of the networking engine can be achieved through calls to the methods in NetworkOptions.

Throws:

java.lang.IllegalStateException - if the network has already been stopped

FDBException

See Also:

NetworkOptions

startNetwork

public void startNetwork(java.util.concurrent.Executor e)
                  throws FDBException,
                         java.lang.IllegalStateException

Initializes networking. Can only be called once. The FoundationDB networking event loop will be run in the specified Executor. This event loop is a blocking operation that is not expected to terminate until the program is complete. This will therefore consume an entire thread from e if e is a thread pool or will completely block the single thread of a single-threaded Executor.

Manual configuration of the networking engine can be achieved through calls on NetworkOptions. These options should be set before a call to this method.

Parameters:

e - the Executor to use to execute network operations on

Throws:

java.lang.IllegalStateException - if the network has already been stopped

FDBException

See Also:

NetworkOptions

stopNetwork

public void stopNetwork()
                 throws FDBException

Stops the FoundationDB networking engine. This can be called only once -- the network cannot be restarted after this call. This call blocks for the completion of the FoundationDB networking engine.

Throws:

FDBException - on errors while stopping the network