<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="/foundationdb/api-general.html#installing-client-binaries" target="_blank">
Installing FoundationDB client binaries</a>). The JAR can be downloaded from
<a href="https://www.foundationdb.org/download/">our website</a>
and then added 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 versions between {@code 510} and {@code 610}).
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 Transaction}s.
Here we give an example. The example relies on a cluster file at the
<a href="/foundationdb/administration.html#default-cluster-file">default location</a>
for your platform and a running server.<br>
<br>
<pre>
{@code
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(610);

    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);
    }
  }
}
}
</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="/foundationdb/data-modeling.html#data-modeling-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>

