FoundationDB Java Bindings

Official Java bindings for FoundationDB, a distributed transactional key-value store with ACID guarantees. Provides high-performance access to structured data across clusters with automatic transaction retry, type-safe key encoding, and multi-tenancy support.

Package Information

• Maven Coordinates: com.apple.foundationdb:fdb-java
• Version: 7.4.3
• Minimum Java Version: Java 8+
• Installation:

  <dependency>
      <groupId>com.apple.foundationdb</groupId>
      <artifactId>fdb-java</artifactId>
      <version>7.4.3</version>
  </dependency>

Quick Start

import com.apple.foundationdb.*;

FDB fdb = FDB.selectAPIVersion(740);
try (Database db = fdb.open()) {
    db.run(tr -> {
        tr.set("key".getBytes(), "value".getBytes());
        return null;
    });
}

See Quick Start Guide for detailed setup instructions.

Core Concepts

Architecture

• FDB: Singleton entry point, manages API version and network lifecycle
• Database: Connection to cluster, provides automatic retry loops
• Transaction: ACID operations with snapshot isolation
• Tuple: Type-safe key encoding preserving lexicographic ordering
• Subspace: Namespace abstraction for key organization
• Directory Layer: Hierarchical namespace management
• Tenant: Isolated key-space for multi-tenancy

Key Features

• Automatic Retry: Database.run() handles transient errors automatically
• Async Operations: CompletableFuture-based non-blocking APIs
• Type-Safe Keys: Tuple encoding for structured keys
• Multi-Tenancy: Tenant isolation for shared deployments
• Range Queries: Efficient range scans with streaming results
• Atomic Operations: Built-in atomic mutations (ADD, MAX, MIN, etc.)

Quick Reference

Essential Imports

import com.apple.foundationdb.*;
import com.apple.foundationdb.tuple.Tuple;
import com.apple.foundationdb.subspace.Subspace;
import com.apple.foundationdb.directory.DirectoryLayer;
import java.util.concurrent.CompletableFuture;

Common Operations

Transaction Patterns

Key Constraints

• Key Size: Maximum 10,000 bytes (10KB)
• Value Size: Maximum 100,000 bytes (100KB)
• System Keys: Keys starting with 0xFF are reserved
• Transaction Size: Default limit 10MB (configurable)
• Transaction Timeout: Default 5 seconds (configurable)

Resource Management

• Always close Database, Transaction, and Tenant objects
• Use try-with-resources for automatic cleanup
• Network thread starts automatically on first open()
• Call FDB.stopNetwork() only on application shutdown

Documentation Structure

Guides

• Quick Start - Get started in minutes
  • Installation and setup
  • Basic usage patterns
  • Key concepts introduction

Examples

• Real-World Scenarios - Common patterns

  • User management systems
  • Atomic counters
  • Secondary indexes
  • Batch operations
  • Multi-tenant applications
  • Async patterns

• Edge Cases - Advanced scenarios

  • Null handling
  • Error recovery
  • Large range processing
  • Transaction size limits
  • Concurrent access patterns

Reference

Complete API documentation:

• Core Database Operations - FDB initialization, database connections, lifecycle
• Transaction Operations - ACID transactions, retry logic, conflict management
• Data Operations - Read, write, clear, range queries, atomic mutations
• Tuple Encoding - Type-safe key encoding, packing/unpacking
• Subspace Operations - Namespace management, key organization
• Directory Layer - Hierarchical namespace management
• Tenant Management - Multi-tenancy, tenant isolation
• Async Operations - Non-blocking APIs, async iteration
• Configuration Options - Network, database, transaction options
• Advanced Features - Watches, versionstamps, blob granules, locality

Common Patterns

Basic Transaction

db.run(tr -> {
    tr.set("key".getBytes(), "value".getBytes());
    return null;
});

Read with Null Check

String value = db.run(tr -> {
    byte[] result = tr.get("key".getBytes()).join();
    return result != null ? new String(result) : null;
});

Range Query

db.read(tr -> {
    for (KeyValue kv : tr.getRange("prefix:".getBytes(), "prefix;".getBytes())) {
        // Process key-value pair
    }
    return null;
});

Tuple Keys

Tuple key = Tuple.from("users", 1001, "profile");
byte[] packed = key.pack();
db.run(tr -> {
    tr.set(packed, "data".getBytes());
    return null;
});

Subspace Organization

Subspace users = new Subspace(Tuple.from("users"));
byte[] key = users.pack(Tuple.from(1001));
db.run(tr -> {
    tr.set(key, "data".getBytes());
    return null;
});

Thread Safety

• FDB objects: Not thread-safe
• Database objects: Can be shared, but transaction creation not synchronized
• Transaction objects: Each thread should use its own transaction
• Subspace/Tuple objects: Immutable, safe to share

Important Notes

Initialization

• Must call FDB.selectAPIVersion(version) before any operations
• Can only be called once per JVM lifetime
• Network thread starts automatically on first open()

Transactions

• Always commit transactions, even read-only ones
• Use Database.run() for automatic retry on conflicts
• Transaction objects are invalid after onError()
• Default timeout: 5 seconds, size limit: 10MB

Error Handling

• FDBException.isRetryable() indicates if retry is appropriate
• Use Transaction.onError() for manual retry logic
• Non-retryable errors should be handled by application

Multi-Tenancy

• Opening tenant doesn't validate existence (errors on first use)
• Tenants must be empty before deletion
• Tenant names are byte arrays (often packed Tuples)

Getting Help

• See Quick Start Guide for setup
• Review Real-World Scenarios for patterns
• Check API Reference for detailed documentation
• Consult Edge Cases for advanced scenarios