mirror of
https://github.com/apple/foundationdb.git
synced 2025-05-14 09:58:50 +08:00
92 lines
4.0 KiB
HTML
92 lines
4.0 KiB
HTML
<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>
|
|
|