Implementation:Lance format Lance JNI FFI

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

Overview

JNI FFI defines the JNIEnvExt extension trait that augments the standard JNI environment with a comprehensive set of helper methods for extracting typed values from Java objects, handling Java Optional wrappers, and converting between Java and Rust collection types.

Description

The JNIEnvExt trait extends JNIEnv with methods that abstract the verbose JNI calling conventions into concise, type-safe Rust operations. The trait provides:

Collection extraction methods:

• get_integers, get_longs, get_strings - Extract typed vectors from Java List objects.
• get_strings_array - Convert a Java String[] array to Vec<String> (unsafe, requires valid input).

Optional value extraction:

• get_string_opt, get_int_opt, get_long_opt, get_u64_opt, get_boolean_opt, get_f32_opt, get_bytes_opt - Extract values from Java Optional<T> wrappers, returning Rust Option<T>.
• get_strings_opt, get_ints_opt, get_list_opt - Extract optional collections.

Method-based extraction:

• get_string_from_method, get_u32_from_method, get_u64_from_method, get_boolean_from_method, get_f32_from_method, get_vec_f32_from_method, get_int_as_usize_from_method - Call a named getter method on a Java object and extract the typed result.
• get_optional_usize_from_method, get_optional_i32_from_method, get_optional_u32_from_method, get_optional_u64_from_method, get_optional_i64_from_method, get_optional_string_from_method - Call getter methods that return Java Optional types.

Specialized extraction:

• get_fts_operator_from_method - Extract a full-text search Operator enum from a Java object.
• get_occur_from_method - Extract a full-text search Occur enum from a Java object.
• get_optional_from_method and get_optional - Generic methods that accept a closure for custom extraction logic.

The implementation handles the Java Optional pattern by calling isPresent() and get() methods, converting null or absent values to Rust None.

Usage

Use this module whenever JNI binding code needs to extract values from Java objects. It is imported throughout the JNI crate and is the primary mechanism for bridging Java types to Rust types in all JNI entry points.

Code Reference

Source Location

java/lance-jni/src/ffi.rs

Signature

pub trait JNIEnvExt {
    fn get_integers(&mut self, obj: &JObject) -> Result<Vec<i32>>;
    fn get_longs(&mut self, obj: &JObject) -> Result<Vec<i64>>;
    fn get_strings(&mut self, obj: &JObject) -> Result<Vec<String>>;
    fn get_string_opt(&mut self, obj: &JObject) -> Result<Option<String>>;
    fn get_int_opt(&mut self, obj: &JObject) -> Result<Option<i32>>;
    fn get_long_opt(&mut self, obj: &JObject) -> Result<Option<i64>>;
    fn get_boolean_opt(&mut self, obj: &JObject) -> Result<Option<bool>>;
    fn get_f32_opt(&mut self, obj: &JObject) -> Result<Option<f32>>;
    fn get_bytes_opt(&mut self, obj: &JObject) -> Result<Option<&[u8]>>;
    fn get_string_from_method(&mut self, obj: &JObject, method_name: &str) -> Result<String>;
    fn get_u32_from_method(&mut self, obj: &JObject, method_name: &str) -> Result<u32>;
    fn get_boolean_from_method(&mut self, obj: &JObject, method_name: &str) -> Result<bool>;
    fn get_optional<T, F>(&mut self, obj: &JObject, f: F) -> Result<Option<T>>
    where
        F: FnOnce(&mut JNIEnv, JObject) -> Result<T>;
    // ... additional methods
}

impl JNIEnvExt for JNIEnv<'_> { /* ... */ }

Import

use crate::ffi::JNIEnvExt;

I/O Contract

Direction	Type	Description
Input	&JObject	Java object to extract values from (e.g., Optional, List, or domain object)
Input	&str (method_name)	Name of the Java getter method to invoke
Output	Result<T>	Extracted Rust value (e.g., String, i32, bool, Vec<T>)
Output	Result<Option<T>>	Extracted optional Rust value from Java Optional<T>

Usage Examples

use crate::ffi::JNIEnvExt;

fn extract_scan_params(env: &mut JNIEnv, params: &JObject) -> Result<ScanConfig> {
    // Extract optional string filter
    let filter = env.get_string_opt(params)?;

    // Extract integer from a method call
    let batch_size = env.get_int_as_usize_from_method(params, "getBatchSize")?;

    // Extract optional u32 from a method returning Optional<Integer>
    let limit = env.get_optional_usize_from_method(params, "getLimit")?;

    // Extract boolean directly from a method
    let with_row_id = env.get_boolean_from_method(params, "isWithRowId")?;

    // Extract a list of strings
    let columns = env.get_strings(params)?;

    Ok(ScanConfig { filter, batch_size, limit, with_row_id, columns })
}

Related Pages

• Lance_format_Lance_JNI_Traits - Companion traits for Rust-to-Java conversion (IntoJava, FromJObject)
• Lance_format_Lance_JNI_BlockingDataset - Primary consumer of JNIEnvExt methods
• Lance_format_Lance_JNI_BlockingScanner - Uses JNIEnvExt for scanner parameter extraction
• Lance_format_Lance_JNI_Utils - Higher-level utility functions built on JNIEnvExt