Implementation:Lance format Lance JNI Traits

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

Overview

JNI Traits defines the core type conversion traits and collection helper functions that enable bidirectional conversion between Rust types and Java objects across the entire JNI binding layer.

Description

This module provides the foundational trait definitions and implementations for the Java-Rust bridge:

Core traits:

• FromJObject<T> - Extracts a Rust value of type T from a JObject without needing the JNI environment. Implemented for primitive wrappers: i32, i64, f32, f64.
• FromJObjectWithEnv<T> - Extracts a Rust value of type T from a JObject using the JNI environment for method calls. Implemented for Option<i64>, Vec<i32> (from JIntArray), Vec<u32> (from JLongArray), and i32.
• FromJString - Extracts a Rust String from a JString.
• IntoJava - Converts a Rust type into a Java JObject. Implemented for &String, HashMap<String, String>, and various JLance<T> wrappers.
• JMapExt - Extension trait for JMap with typed accessors: get_string, get_i32, get_i64, get_f32, get_f64.

Collection helpers:

• export_vec - Converts a Rust slice of IntoJava items to a Java ArrayList.
• import_vec - Converts a Java List to a Vec<JObject> by calling size() and get(i).
• import_vec_to_rust - Converts a Java List to a Vec<T> using a custom extractor closure.
• import_vec_from_method - Calls a getter method that returns a List, then converts it using an extractor.

JLance wrapper: The JLance<T> newtype provides IntoJava implementations for types that need explicit boxing:

• JLance<Vec<i32>> - Converts to a Java int[] array.
• JLance<Vec<u32>> - Converts to a Java long[] array (widening to avoid sign issues).
• JLance<usize>, JLance<i64> - Converts to Java Long objects.
• JLance<i32> - Converts to a Java Integer object.
• JLance<Option<usize>> - Converts to a Java Long or null.

Usage

Use this module whenever JNI code needs to convert between Rust and Java types. These traits are imported throughout the entire JNI crate and form the type conversion backbone of the binding layer.

Code Reference

Source Location

java/lance-jni/src/traits.rs

Signature

pub trait FromJObject<T> {
    fn extract(&self) -> Result<T>;
}

pub trait FromJObjectWithEnv<T> {
    fn extract_object(&self, env: &mut JNIEnv<'_>) -> Result<T>;
}

pub trait FromJString {
    fn extract(&self, env: &mut JNIEnv) -> Result<String>;
}

pub trait IntoJava {
    fn into_java<'a>(self, env: &mut JNIEnv<'a>) -> Result<JObject<'a>>;
}

pub trait JMapExt {
    fn get_string(&self, env: &mut JNIEnv, key: &str) -> Result<Option<String>>;
    fn get_i32(&self, env: &mut JNIEnv, key: &str) -> Result<Option<i32>>;
    fn get_i64(&self, env: &mut JNIEnv, key: &str) -> Result<Option<i64>>;
    fn get_f32(&self, env: &mut JNIEnv, key: &str) -> Result<Option<f32>>;
    fn get_f64(&self, env: &mut JNIEnv, key: &str) -> Result<Option<f64>>;
}

pub struct JLance<T>(pub T);

pub fn export_vec<'a, 'b, T>(env: &mut JNIEnv<'a>, vec: &'b [T]) -> Result<JObject<'a>>
where &'b T: IntoJava;

pub fn import_vec<'local>(env: &mut JNIEnv<'local>, obj: &JObject) -> Result<Vec<JObject<'local>>>;

pub fn import_vec_to_rust<T, F>(env: &mut JNIEnv<'_>, obj: &JObject<'_>, extractor: F) -> Result<Vec<T>>
where F: FnMut(&mut JNIEnv<'_>, JObject<'_>) -> Result<T>;

pub fn import_vec_from_method<T, F>(
    env: &mut JNIEnv<'_>, java_obj: &JObject<'_>,
    method_name: &str, extractor: F,
) -> Result<Vec<T>>
where F: FnMut(&mut JNIEnv<'_>, JObject<'_>) -> Result<T>;

Import

use crate::traits::{FromJObject, FromJObjectWithEnv, FromJString, IntoJava, JLance, JMapExt};
use crate::traits::{export_vec, import_vec, import_vec_to_rust, import_vec_from_method};

I/O Contract

Direction	Type	Description
Input	JObject	Java object to extract a Rust value from
Input	&JNIEnv	JNI environment for method calls during extraction
Input	&[T] where &T: IntoJava	Rust slice to export as a Java ArrayList
Output	Result<T>	Extracted Rust value from a Java object
Output	Result<JObject>	Java object created from a Rust value
Output	Result<Vec<T>>	Rust vector extracted from a Java List

Usage Examples

use crate::traits::{IntoJava, FromJObjectWithEnv, export_vec, import_vec_from_method, JLance};

// Export a Rust vector to a Java ArrayList
fn export_fragments(env: &mut JNIEnv, fragments: &[Fragment]) -> Result<JObject> {
    export_vec(env, fragments)
}

// Import a Java list to a Rust vector
fn import_fragment_ids(env: &mut JNIEnv, obj: &JObject) -> Result<Vec<i32>> {
    import_vec_from_method(env, obj, "getFragmentIds", |env, elem| {
        elem.extract_object(env)
    })
}

// Convert a Rust usize to a Java Long
fn to_java_long(env: &mut JNIEnv, value: usize) -> Result<JObject> {
    JLance(value).into_java(env)
}

// Convert a HashMap to a Java HashMap
fn to_java_map(env: &mut JNIEnv, map: HashMap<String, String>) -> Result<JObject> {
    map.into_java(env)
}

Related Pages

• Lance_format_Lance_JNI_FFI - JNIEnvExt trait that complements these conversion traits
• Lance_format_Lance_JNI_BlockingDataset - Major consumer of all conversion traits
• Lance_format_Lance_JNI_Transaction - Implements IntoJava and FromJObjectWithEnv for transaction types
• Lance_format_Lance_JNI_Fragment - Uses export_vec and import_vec for fragment lists
• Lance_format_Lance_JNI_Schema - Implements IntoJava for Schema using these traits