Implementation:Lance format Lance Java RestAdapter

Knowledge Sources	Lance
Domains	Java_SDK, Dataset_Management
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The RestAdapter class wraps a namespace backend (such as DirectoryNamespace) and exposes it via a REST API server. It implements both Closeable and AutoCloseable, enabling use in try-with-resources blocks. The class delegates to a native Rust implementation via JNI, loading the native library through JniLoader.ensureLoaded().

The adapter manages a native handle (nativeRestAdapterHandle) and a server lifecycle with start(), stop(), and getPort() methods. It supports binding to a specific host and port or using OS-assigned ports (by specifying port 0). The default host is 127.0.0.1 and the default port is 2333.

The class validates inputs at construction time, rejecting null or empty namespace implementations, null backend configs, and out-of-range ports. Server state is tracked to prevent double-start and ensure idempotent stop behavior.

Usage

Use RestAdapter primarily for testing RestNamespace implementations. It allows spinning up a local REST server backed by any namespace implementation, which clients can then connect to for integration testing.

Code Reference

Source Location

java/src/main/java/org/lance/namespace/RestAdapter.java

Signature

public class RestAdapter implements Closeable, AutoCloseable {
    public RestAdapter(String namespaceImpl, Map<String, String> backendConfig,
                       String host, Integer port);
    public RestAdapter(String namespaceImpl, Map<String, String> backendConfig);
    public void start();
    public int getPort();
    public void stop();
    public void close();
}

Import

import org.lance.namespace.RestAdapter;

I/O Contract

Constructor Inputs

Parameter	Type	Required	Description
namespaceImpl	String	Yes	The namespace implementation type (e.g., "dir" for DirectoryNamespace)
backendConfig	Map<String, String>	Yes	Configuration properties for the backend namespace
host	String	No	Host to bind to (defaults to 127.0.0.1 if null)
port	Integer	No	Port to bind to; 0 for OS-assigned (defaults to 2333 if null); must be 0-65535

Methods

Method	Return Type	Description
start()	void	Starts the REST server in a background thread. Throws IllegalStateException if already started or not initialized.
getPort()	int	Returns the actual port the server is listening on (useful when port 0 was specified). Returns 0 if not started.
stop()	void	Stops the server. Idempotent.
close()	void	Stops the server and releases the native handle.

Usage Examples

// Start a REST adapter for testing
Map<String, String> backendConfig = new HashMap<>();
backendConfig.put("root", "/tmp/test-data");

try (RestAdapter adapter = new RestAdapter("dir", backendConfig, null, 0)) {
    adapter.start();
    int port = adapter.getPort(); // OS-assigned port

    // Connect with RestNamespace client
    Map<String, String> clientConfig = Map.of(
        "uri", "http://127.0.0.1:" + port
    );
    RestNamespace client = new RestNamespace();
    client.initialize(clientConfig, allocator);

    // Perform namespace operations via REST...
}
// Server automatically stopped and resources released

Related Pages

• Lance_format_Lance_Java_DynamicContextProvider -- Context provider for authentication headers in namespace operations
• Lance_format_Lance_Java_NamespaceStorageOptions -- Storage options provider backed by namespace
• Lance_format_Lance_Java_StorageOptionsProvider -- Interface for cloud storage credential provisioning