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 `520`.
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 `createCluster()`, or started explicitly with a call to `startNetwork()`.

### Field Summary

Fields
`static java.util.concurrent.ExecutorService` `DEFAULT_EXECUTOR`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`Cluster` `createCluster()` Connects to the cluster specified by the default fdb.cluster file.
`Cluster` `createCluster(java.lang.String clusterFilePath)` Connects to the cluster specified by `clusterFilePath`.
`Cluster` `createCluster(java.lang.String clusterFilePath, java.util.concurrent.Executor e)` Connects to the cluster specified by `clusterFilePath`.
`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.
`Database` `open()` Initializes networking, connects with the default fdb.cluster file, and opens the database.
`Database` `open(java.lang.String clusterFilePath)` Initializes networking, connects to the cluster specified by `clusterFilePath` and opens the database.
`Database` `open(java.lang.String clusterFilePath, java.util.concurrent.Executor e)` Initializes networking, connects to the cluster specified by `clusterFilePath` and opens the database.
`NetworkOptions` `options()` Returns a set of options that can be set on a the FoundationDB API.
`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()` and implicitly by calls to `open()` and `createCluster()` (and their respective 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`

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

#### createCluster

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

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

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

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

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

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, connects with the default fdb.cluster file, and opens the database.

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, connects to the cluster specified by `clusterFilePath` and opens the database.

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,
                         java.util.concurrent.Executor e)
                  throws FDBException

Initializes networking, connects to the cluster specified by `clusterFilePath` and opens the database.

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`

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