<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.cie.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 510}).
With this API object you can then open {@link com.apple.cie.foundationdb.Cluster Cluster}s and
{@link com.apple.cie.foundationdb.Database Database}s and start using
{@link com.apple.cie.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.cie.foundationdb.*;
import Function;
import Tuple;
public class Example {
public static void main(String[] args) {
FDB fdb = FDB.selectAPIVersion(510);
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.cie.foundationdb.tuple Tuple API}</h3>
The {@link com.apple.cie.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.cie.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.cie.foundationdb.directory Directory API}</h3>
The {@link com.apple.cie.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.cie.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>