Skip navigation links

FoundationDB Java Client API

This documents the client API for using FoundationDB from Java.

See: Description

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

    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.
Skip navigation links