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 JAR can be downloaded from our website and then added 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 versions between 510 and 710). 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.apple.foundationdb.Database;
import com.apple.foundationdb.FDB;
import com.apple.foundationdb.tuple.Tuple;

public class Example {
  public static void main(String[] args) {
    FDB fdb = FDB.selectAPIVersion(710);

    try(Database db = fdb.open()) {
      // Run an operation on the database
      db.run(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(tr -> {
        byte[] result = tr.get(Tuple.from("hello").pack()).join();
        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.

Packages

Package	Description
com.apple.foundationdb	Provides an API for the FoundationDB transactional key/value store.
com.apple.foundationdb.async	Provides additional constructs for asynchronous programming against Java's CompletableFutures.
com.apple.foundationdb.directory	Provides tools for managing hierarchically related key subspaces.
com.apple.foundationdb.subspace	Provides a convenient way to define namespaces for different categories of data.
com.apple.foundationdb.tuple	Provides a set of utilities for serializing and deserializing typed data for use in FoundationDB.