FDB (FoundationDB Java Client API)

java.lang.Object
- com.foundationdb.FDB

```
public class FDB
extends 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 300.
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.

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().

Method Summary

Methods
Modifier and Type	Method and Description
`Cluster`	`createCluster()` Connects to the cluster specified by the default fdb.cluster file.
`Cluster`	`createCluster(String clusterFilePath)` Connects to the cluster specified by `clusterFilePath`.
`Cluster`	`createCluster(String clusterFilePath, Executor e)` Connects to the cluster specified by `clusterFilePath`.
`Database`	`open()` Initializes networking, connects with the default fdb.cluster file, and opens the default database.
`Database`	`open(String clusterFilePath)` Initializes networking, connects to the cluster specified by `clusterFilePath` and opens the database with the default name.
`Database`	`open(String clusterFilePath, byte[] databaseName)` Initializes networking, connects to the cluster specified by `clusterFilePath` and opens the database with the specified name.
`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`	`startNetwork()` Initializes networking.
`void`	`startNetwork(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

- 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
  - 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.
    
    Parameters:
    version - the API version required
    
    Returns:
    the FoundationDB API object
    
    Throws:
    
    FDBException
  - createCluster
```
public Cluster createCluster()
                      throws 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 Future that will be set to a FoundationDB Cluster.
    
    Throws:
    
    FDBException - on errors encountered starting the FoundationDB networking engine
    
    IllegalStateException - if the network had been previously stopped
  - createCluster
```
public Cluster createCluster(String clusterFilePath)
                      throws 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 Future that will be set to a FoundationDB Cluster.
    
    Throws:
    
    FDBException - on errors encountered starting the FoundationDB networking engine
    
    IllegalStateException - if the network had been previously stopped
  - createCluster
```
public Cluster createCluster(String clusterFilePath,
                    Executor e)
                      throws FDBException,
                             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 execute all callbacks from the Cluster.
    
    Returns:
    a Future that will be set to a FoundationDB Cluster.
    
    Throws:
    
    FDBException - on errors encountered starting the FoundationDB networking engine
    
    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 default database. The default database name of "DB" is used.
    
    Returns:
    a Future that will be set to a FoundationDB Database
    
    Throws:
    
    FDBException
  - open
```
public Database open(String clusterFilePath)
              throws FDBException
```
    Initializes networking, connects to the cluster specified by clusterFilePath and opens the database with the default name. The default database name of "DB" is 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 Future that will be set to a FoundationDB Database
    
    Throws:
    
    FDBException
  - open
```
public Database open(String clusterFilePath,
            byte[] databaseName)
              throws FDBException
```
    Initializes networking, connects to the cluster specified by clusterFilePath and opens the database with the specified name. As of the current API version, the only database that can be opened has a name equivalent to the ASCII encoding for "DB". (This byte array created using "DB".getBytes()). Therefore, this function provides no advantage over open(String).
    
    Parameters:
    clusterFilePath - the cluster file defining the FoundationDB cluster. This can be null if the default fdb.cluster file is to be used.
    databaseName - the name of the database to load. Must be a byte array equivelent to "DB".
    
    Returns:
    a Future that will be set to a FoundationDB Database
    
    Throws:
    
    FDBException
  - startNetwork
```
public void startNetwork()
                  throws FDBException,
                         IllegalStateException
```
    Initializes networking. Can only be called once. This version of startNetwork() will use the default thread pool to execute the FoundationDB network.
    
    Configuration of the networking engine can be achieved through calls to the methods in NetworkOptions.
    
    Throws:
    
    IllegalStateException - if the network has already been stopped
    
    FDBException
    See Also:
    NetworkOptions
  - startNetwork
```
public void startNetwork(Executor e)
                  throws FDBException,
                         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 in complete. This will therefore consume an entire thread from e if e is a thread pool or will completely block operation 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.
    
    Throws:
    
    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

Class FDB

Setting API version

Getting a database

Client networking

Method Summary

Methods inherited from class java.lang.Object

Method Detail

options

selectAPIVersion

createCluster

createCluster

createCluster

open

open

open

startNetwork

startNetwork

stopNetwork