<HTML>
<BODY>
This documents the client API for using FoundationDB from Java.<br>
<br>
<h3>Installation</h3>
FoundationDB's Java bindings rely on native libraries that are installed as part of the 
FoundationDB client binaries installation (see 
<a href="/documentation/api-general.html#installing-client-binaries" target="_blank">
Installing FoundationDB client binaries</a>). The FoundationDB Java bindings are available
through Artifactory. To use them in your Maven-enabled project, add a dependency to your 
pom.xml like: <br>
<pre>
{@code
<dependency>
    <groupId>com.apple.cie.foundationdb</groupId>
    <artifactId>fdb-java-completable</artifactId>
    <version>VERSION</version>
</dependency>
}
</pre>
Alternatively, simply download the JAR from
<a href="https://files.foundationdb.org/fdb-java-completable/">Artifactory</a>
and add it to your classpath.<br>
<br>
<h3>Getting started</h3>
To start using FoundationDB from Java, create an instance of the 
{@link com.apple.foundationdb.FDB FoundationDB API interface} with the version of the
API that you want to use (this release of the FoundationDB Java API supports only version {@code 500}).
With this API object you can then open {@link com.apple.foundationdb.Cluster Cluster}s and
{@link com.apple.foundationdb.Database Database}s and start using
{@link com.apple.foundationdb.Transaction Transactions}s.
Here we give an example. The example relies on a cluster file at the
<a href="/documentation/api-general.html#default-cluster-file">default location</a> 
for your platform and a running server.<br>
<br>
<pre>
{@code
import com.apple.foundationdb.*;
import Function;
import Tuple;

public class Example {
  public static void main(String[] args) {
    FDB fdb = FDB.selectAPIVersion(500);
    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);
  }
}
}
</pre>
<h3>FoundationDB {@link com.apple.foundationdb.tuple Tuple API}</h3>
The {@link com.apple.foundationdb.tuple 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 
{@code Tuple}s and used as keys sort in predictable and useful ways. See the 
{@link com.apple.foundationdb.tuple Tuple class documentation} for information about use in Java
and <a href="/documentation/data-modeling.html#tuples">general Tuple documentation</a>
for information about how Tuples sort and can be used to efficiently model data.
<br>
<h3>FoundationDB {@link com.apple.foundationdb.directory Directory API}</h3>
The {@link com.apple.foundationdb.directory 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 {@link com.apple.foundationdb.subspace.Subspace 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.
</BODY>
</HTML>

