FoundationDB Java Client API

This documents the client API for using FoundationDB from Java.

Installation

FoundationDB's Java bindings rely on native libraries that are installed as part of the FoundationDB client binaries installation (see Installing FoundationDB client binaries). The FoundationDB Java bindings are available through Maven Central. To use them in your Maven-enabled project, add a dependency to your pom.xml like:

<dependency>
    <groupId>com.foundationdb</groupId>
    <artifactId>fdb-java</artifactId>
    <version>3.0.2</version>
</dependency>

Alternatively, simply download the JAR from the FoundationDB downloads page and add it to your classpath.

Getting started

To start using FoundationDB from Java, create an instance of the FoundationDB API interface with the version of the API that you want to use (this release of the FoundationDB Java API supports only versions 23-300). With this API object you can then open Clusters and Databases and start using Transactions. Here we give an example. The example relies on a cluster file at the default location for your platform and a running server.

import com.foundationdb.*;
import com.foundationdb.async.Function;
import com.foundationdb.tuple.Tuple;

public class Example {
  public static void main(String[] args) {
    FDB fdb = FDB.selectAPIVersion(300);
    Database db = fdb.open();

    // Run an operation on the database
    db.run(new Function<Transaction, Void>() {
      public Void apply(Transaction tr) {
        tr.set(Tuple.from("hello").pack(), Tuple.from("world").pack());
        return null;
      }
    });

    // Get the value of 'hello' from the database
    String hello = db.run(new Function<Transaction, String>() {
      public String apply(Transaction tr) {
        byte[] result = tr.get(Tuple.from("hello").pack()).get();
        return Tuple.fromBytes(result).getString(0);
      }
    });
    System.out.println("Hello " + hello);
  }
}

FoundationDB Tuple API

The Tuple API is provided with the core Java API for FoundationDB. This layer is provided in some form in all official language bindings. It enables cross-language support for storing and retrieving typed data from the binary data that FoundationDB supports. And, just as importantly, data packed into Tuples and used as keys sort in predictable and useful ways. See the Tuple class documentation for information about use in Java and general Tuple documentation for information about how Tuples sort and can be used to efficiently model data.

FoundationDB Directory API

The Directory API is provided with the core Java API for FoundationDB. This layer is provided in some form in all official language bindings. The FoundationDB API provides directories as a tool for managing related Subspaces. Directories are a recommended approach for administering applications. Each application should create or open at least one directory to manage its subspaces. Directories are identified by hierarchical paths analogous to the paths in a Unix-like file system. A path is represented as a List of strings. Each directory has an associated subspace used to store its content. The layer maps each path to a short prefix used for the corresponding subspace. In effect, directories provide a level of indirection for access to subspaces.

Futures and asynchronous operation

Asynchronous FoundationDB operations return Futures. A Future can be used in a blocking way using the get() method or in a fully-asynchronous way using the map() and flatMap() methods. Generally, the blocking style is more straightforward and the asynchronous style is more efficient. Mixing the two styles correctly can be tricky, so consider choosing one or the other. See the async Package documentation for more information.