Implementation:Lance format Lance JNI Transaction

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

Overview

JNI Transaction is the Rust-side JNI binding that provides bidirectional conversion between Lance transaction types (operations, rewrite groups, indices, UUIDs) and their Java counterparts, enabling Java applications to read, construct, and commit dataset transactions.

Description

This module implements IntoJava and FromJObjectWithEnv for the core transaction-related types, enabling full round-trip serialization between Java and Rust:

Type conversions (Rust to Java):

• &RewriteGroup - Converts old and new fragment lists to a Java RewriteGroup object.
• &RewrittenIndex - Converts old/new UUIDs, index details (protobuf Any), and version to Java.
• &DataReplacementGroup - Converts fragment ID and replacement data file to Java.
• &UpdateMode - Converts the enum (RewriteRows / RewriteColumns) to a Java enum constant.
• Uuid - Converts a Rust UUID to a Java java.util.UUID via string serialization.

Type conversions (Java to Rust):

• RewriteGroup - Extracts old and new fragment lists from the Java object.
• RewrittenIndex - Extracts UUIDs, protobuf details (type URL and byte value), and version.
• IndexMetadata - Extracts UUID, field IDs, name, dataset version, fragment bitmap (as RoaringBitmap), index details, version, creation timestamp, and base ID.
• DataReplacementGroup - Extracts fragment ID and replacement data file.
• UpdateMode - Extracts the enum variant from its string representation.
• Uuid - Parses a UUID from the Java object's string representation.

JNI entry points:

• Java_org_lance_Dataset_nativeReadTransaction - Reads the current transaction from a dataset, returning a Java transaction object or null if no transaction exists.
• convert_to_java_transaction - Converts a Rust Transaction to a Java transaction object, mapping all operation variants to their Java equivalents.

Transaction operations supported: The module handles various Lance operation types including Append, Overwrite/Write, Delete, Merge, Restore, Rewrite, CreateIndex, ReserveFragments, Update, DataReplacement, and others, converting their fields (fragments, schemas, parameters) to/from Java representations.

Usage

Use this module when implementing or extending the Java transaction API. It enables Java applications to inspect dataset transactions, build custom operations, and commit them to datasets using the BlockingDataset::commit method.

Code Reference

Source Location

java/lance-jni/src/transaction.rs

Signature

impl IntoJava for &RewriteGroup { /* ... */ }
impl IntoJava for &RewrittenIndex { /* ... */ }
impl IntoJava for &DataReplacementGroup { /* ... */ }
impl IntoJava for &UpdateMode { /* ... */ }
impl IntoJava for Uuid { /* ... */ }

impl FromJObjectWithEnv<RewriteGroup> for JObject<'_> { /* ... */ }
impl FromJObjectWithEnv<RewrittenIndex> for JObject<'_> { /* ... */ }
impl FromJObjectWithEnv<IndexMetadata> for JObject<'_> { /* ... */ }
impl FromJObjectWithEnv<DataReplacementGroup> for JObject<'_> { /* ... */ }
impl FromJObjectWithEnv<UpdateMode> for JObject<'_> { /* ... */ }
impl FromJObjectWithEnv<Uuid> for JObject<'_> { /* ... */ }

#[no_mangle]
pub extern "system" fn Java_org_lance_Dataset_nativeReadTransaction<'local>(
    mut env: JNIEnv<'local>,
    java_dataset: JObject,
) -> JObject<'local>;

pub(crate) fn convert_to_java_transaction<'local>(
    env: &mut JNIEnv<'local>,
    transaction: Transaction,
    java_dataset: &JObject,
) -> Result<JObject<'local>>;

Import

use crate::transaction::convert_to_java_transaction;

I/O Contract

Direction	Type	Description
Input	JObject (Java Dataset)	Dataset to read the transaction from
Input	JObject (Java RewriteGroup)	Java object containing old and new fragment lists
Input	JObject (Java RewrittenIndex)	Java object with UUID pairs and protobuf index details
Input	JObject (Java IndexMetadata)	Java object with index UUID, fields, name, version, and bitmap
Output	JObject (Java Transaction)	Full transaction object with operation, version, and metadata
Output	JObject (Java UUID)	UUID created via java.util.UUID.fromString
Output	JObject (Java RewriteGroup)	Java object with old/new fragment ArrayLists

Usage Examples

// Java side: reading a transaction from a dataset
import org.lance.Dataset;
import org.lance.transaction.Transaction;

Dataset dataset = Dataset.open("/path/to/dataset");
Transaction txn = dataset.readTransaction();

if (txn != null) {
    String operationType = txn.getOperationType();
    long readVersion = txn.getReadVersion();
}

// Rust JNI side: converting a rewrite group to Java
impl IntoJava for &RewriteGroup {
    fn into_java<'a>(self, env: &mut JNIEnv<'a>) -> Result<JObject<'a>> {
        let old_fragments = export_vec(env, &self.old_fragments)?;
        let new_fragments = export_vec(env, &self.new_fragments)?;
        Ok(env.new_object(
            "org/lance/operation/RewriteGroup",
            "(Ljava/util/List;Ljava/util/List;)V",
            &[JValue::Object(&old_fragments), JValue::Object(&new_fragments)],
        )?)
    }
}

Related Pages

• Lance_format_Lance_JNI_BlockingDataset - Commits transactions via BlockingDataset::commit
• Lance_format_Lance_JNI_Fragment - Fragment metadata types referenced in transaction operations
• Lance_format_Lance_JNI_Traits - IntoJava and FromJObjectWithEnv traits implemented here
• Lance_format_Lance_JNI_Schema - Schema conversion used in transaction operations
• Lance_format_Lance_JNI_Optimize - Compaction operations that produce rewrite results