Package com.apple.foundationdb
Class FDB
java.lang.Object
com.apple.foundationdb.FDB
The starting point for accessing FoundationDB.
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.
Setting API version
The FoundationDB API is accessed with a call toselectAPIVersion(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 latest supported API version
is defined as ApiVersion.LATEST.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 aDatabase
object to use is
to call open()
.
Client networking
The network is started either implicitly with a call to a variant ofopen()
or started explicitly with a call to startNetwork()
.
-
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionDeprecated.createCluster
(String clusterFilePath) Deprecated.Useopen(String)
instead.createCluster
(String clusterFilePath, Executor e) Deprecated.Useopen(String, Executor)
instead.void
Disables shutdown hook that stops network thread upon process shutdown.void
enableDirectBufferQuery
(boolean enabled) Enables or disables use of DirectByteBuffers for getRange() queries.protected static boolean
evalErrorPredicate
(int predicate, int code) int
Returns the API version that was selected by theselectAPIVersion()
call.static FDB
instance()
Return the instance of the FDB API singleton.static boolean
Determines if the API version has already been selected.boolean
Determines whethergetRange()
queries can useDirectByteBuffer
fromDirectBufferPool
to copy results.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.Initializes networking if required and connects to the cluster specified byclusterFilePath
.
A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.open
(String clusterFilePath, EventKeeper eventKeeper) Initializes networking if required and connects to the cluster specified byclusterFilePath
.
A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.Initializes networking if required and connects to the cluster specified byclusterFilePath
.
A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.open
(String clusterFilePath, Executor e, EventKeeper eventKeeper) Initializes networking if required and connects to the cluster specified byclusterFilePath
.
A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file.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
Initializes networking.void
Initializes networking.void
Stops the FoundationDB networking engine.
-
Field Details
-
DEFAULT_EXECUTOR
-
-
Method Details
-
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 tostartNetwork()
or implicitly by a call toopen()
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 returntrue
if the user has already calledselectAPIVersion()
and that call has completed successfully.- Returns:
true
if an API version has been selected andfalse
otherwise
-
instance
Return the instance of the FDB API singleton. This method will always return a non-null
value for the singleton, but if theselectAPIVersion()
method has not yet been called, it will throw anFDBException
indicating that an API version has not yet been set.- Returns:
- the FoundationDB API object
- Throws:
FDBException
- ifselectAPIVersion()
has not been called
-
selectAPIVersion
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 callingstopNetwork()
. -
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 theselectAPIVersion()
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 whethergetRange()
queries can useDirectByteBuffer
fromDirectBufferPool
to copy results.- Returns:
true
if direct buffer queries have been enabled andfalse
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 poolbufferSize
- Size of each buffer in bytes
-
createCluster
Deprecated.Useopen()
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 ifstartNetwork()
had been called.- Returns:
- a
CompletableFuture
that will be set to a FoundationDBCluster
. - Throws:
FDBException
- on errors encountered starting the FoundationDB networking engineIllegalStateException
- if the network had been previously stopped
-
createCluster
@Deprecated public Cluster createCluster(String clusterFilePath) throws IllegalStateException, FDBException Deprecated.Useopen(String)
instead.Connects to the cluster specified byclusterFilePath
. If the FoundationDB network has not been started, it will be started in the course of this call as ifstartNetwork()
had been called.- Parameters:
clusterFilePath
- the cluster file defining the FoundationDB cluster. This can benull
if the default fdb.cluster file is to be used.- Returns:
- a
CompletableFuture
that will be set to a FoundationDBCluster
. - Throws:
FDBException
- on errors encountered starting the FoundationDB networking engineIllegalStateException
- if the network had been previously stopped
-
createCluster
@Deprecated public Cluster createCluster(String clusterFilePath, Executor e) throws FDBException, IllegalStateException Deprecated.Useopen(String, Executor)
instead.Connects to the cluster specified byclusterFilePath
. If the FoundationDB network has not been started, it will be started in the course of this call. The suppliedExecutor
will be used as the default for the execution of all callbacks that are produced from using the resultingCluster
.- Parameters:
clusterFilePath
- the cluster file defining the FoundationDB cluster. This can benull
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 FoundationDBCluster
. - Throws:
FDBException
- on errors encountered starting the FoundationDB networking engineIllegalStateException
- if the network had been previously stopped
-
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. 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 FoundationDBDatabase
- Throws:
FDBException
-
open
Initializes networking if required and connects to the cluster specified byclusterFilePath
.
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 benull
if the default fdb.cluster file is to be used.- Returns:
- a
CompletableFuture
that will be set to a FoundationDBDatabase
- Throws:
FDBException
-
open
Initializes networking if required and connects to the cluster specified byclusterFilePath
.
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 benull
if the default fdb.cluster file is to be used.eventKeeper
- the EventKeeper to use for instrumentation calls, ornull
if no instrumentation is desired.- Returns:
- a
CompletableFuture
that will be set to a FoundationDBDatabase
- Throws:
FDBException
-
open
Initializes networking if required and connects to the cluster specified byclusterFilePath
.
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 benull
if the default fdb.cluster file is to be used.e
- theExecutor
to use to execute asynchronous callbacks- Returns:
- a
CompletableFuture
that will be set to a FoundationDBDatabase
- Throws:
FDBException
-
open
public Database open(String clusterFilePath, Executor e, EventKeeper eventKeeper) throws FDBException Initializes networking if required and connects to the cluster specified byclusterFilePath
.
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 benull
if the default fdb.cluster file is to be used.e
- theExecutor
to use to execute asynchronous callbackseventKeeper
- theEventKeeper
to use to record instrumentation metrics, ornull
if no instrumentation is desired.- Returns:
- a
CompletableFuture
that will be set to a FoundationDBDatabase
- Throws:
FDBException
-
startNetwork
Initializes networking. Can only be called once. This version ofstartNetwork()
will create a new thread and execute the networking event loop on that thread. This method is called uponDatabase
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 ofstartNetwork()
that takes anExecutor
.
Configuration of the networking engine can be achieved through calls to the methods inNetworkOptions
.- Throws:
IllegalStateException
- if the network has already been stoppedFDBException
- See Also:
-
startNetwork
Initializes networking. Can only be called once. The FoundationDB networking event loop will be run in the specifiedExecutor
. 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 frome
ife
is a thread pool or will completely block the single thread of a single-threadedExecutor
.
Manual configuration of the networking engine can be achieved through calls onNetworkOptions
. These options should be set before a call to this method.- Parameters:
e
- theExecutor
to use to execute network operations on- Throws:
IllegalStateException
- if the network has already been stoppedFDBException
- See Also:
-
stopNetwork
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
-
evalErrorPredicate
protected static boolean evalErrorPredicate(int predicate, int code)
-
open()
instead.