Implementation:Lance format Lance JNI Namespace

Knowledge Sources	Lance
Domains	Java_Bindings, JNI
Last Updated	2026-02-08 19:33 GMT

Overview

JNI Namespace is the Rust-side JNI binding that exposes Lance namespace and catalog management to Java, supporting both directory-based and REST-based namespace implementations with dynamic context providers for authentication and authorization.

Description

This module provides JNI entry points for the Java namespace classes to interact with the Lance catalog/namespace system. It supports two namespace implementations:

DirectoryNamespace:

• Java_org_lance_namespace_DirectoryNamespace_createNative - Creates a directory-based namespace from a properties map.
• Java_org_lance_namespace_DirectoryNamespace_createNativeWithProvider - Creates a directory-based namespace with a dynamic context provider for runtime configuration.

RestNamespace:

• REST-based namespace operations connecting to a remote catalog service via HTTP, configured through a RestAdapterConfig.

JavaDynamicContextProvider: A key bridge component that wraps a Java object implementing the DynamicContextProvider interface. It:

• Holds a GlobalRef to the Java provider object and an Arc<JavaVM> for thread-safe JVM access.
• Implements the Rust DynamicContextProvider trait by attaching to the JVM thread, calling the Java provideContext(String operation, String objectId) method, and converting the returned Map<String, String> to a Rust HashMap.
• Handles errors gracefully by logging failures and returning empty maps rather than panicking.

Blocking wrappers:

• BlockingDirectoryNamespace - Wraps DirectoryNamespace for synchronous access.
• BlockingRestNamespace - Wraps RestNamespace for synchronous access.

The helper function convert_java_map_to_hashmap converts a Java Map to a Rust HashMap<String, String> by iterating over the JNI map interface.

Usage

Use this module when implementing or extending the Java namespace/catalog API. It enables Java applications to organize datasets into namespaces with either local directory-based or remote REST-based backends, optionally providing dynamic credentials or context per operation.

Code Reference

Source Location

java/lance-jni/src/namespace.rs

Signature

pub struct JavaDynamicContextProvider {
    java_provider: GlobalRef,
    jvm: Arc<jni::JavaVM>,
}

impl JavaDynamicContextProvider {
    pub fn new(env: &mut JNIEnv, java_provider: &JObject) -> Result<Self>;
}

impl DynamicContextProvider for JavaDynamicContextProvider {
    fn provide_context(&self, info: &OperationInfo) -> HashMap<String, String>;
}

pub struct BlockingDirectoryNamespace {
    pub(crate) inner: DirectoryNamespace,
}

pub struct BlockingRestNamespace {
    pub(crate) inner: RestNamespace,
}

Import

use crate::namespace::{JavaDynamicContextProvider, BlockingDirectoryNamespace, BlockingRestNamespace};

I/O Contract

Direction	Type	Description
Input	JObject (properties Map)	Java Map<String, String> containing namespace configuration
Input	JObject (DynamicContextProvider)	Java object implementing the provider interface for dynamic credentials
Input	OperationInfo	Operation name and object ID passed to the context provider
Output	jlong	Native handle pointer to the created namespace object
Output	HashMap<String, String>	Context map returned by the dynamic provider

Usage Examples

// Java side: creating a directory namespace
import org.lance.namespace.DirectoryNamespace;

Map<String, String> properties = new HashMap<>();
properties.put("base_path", "/data/lance-catalog");

DirectoryNamespace namespace = DirectoryNamespace.create(properties);

// Rust JNI side: creating a namespace with a dynamic provider
#[no_mangle]
pub extern "system" fn Java_org_lance_namespace_DirectoryNamespace_createNativeWithProvider(
    mut env: JNIEnv,
    _obj: JObject,
    properties_map: JObject,
    provider_obj: JObject,
) -> jlong {
    ok_or_throw_with_return!(
        env,
        create_directory_namespace_internal(&mut env, properties_map, Some(&provider_obj)),
        0
    )
}

Related Pages

• Lance_format_Lance_JNI_BlockingDataset - Datasets managed within namespaces
• Lance_format_Lance_JNI_Utils - Map conversion utilities used by namespace operations
• Lance_format_Lance_JNI_FFI - JNIEnvExt trait used for value extraction