# 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 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 `Cluster`s and `Database`s and start using `Transaction`s. 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 `Tuple`s 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 `Subspace`s. 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
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 `CompletableFuture`s.
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.