Implementation:Lance format Lance Java JniLoader

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

Overview

Description

JniLoader is a utility class responsible for loading the native Lance JNI library (lance_jni) into the JVM. It uses the JarJniLoader from the QuestDB library to extract and load the native shared library from the /nativelib resource path within the JAR. Upon class loading, it also initializes the Rust-side logger, which can be controlled via the LANCE_LOG environment variable (e.g., export LANCE_LOG=debug).

Usage

JniLoader has a private constructor and cannot be instantiated. Other Lance Java classes call JniLoader.ensureLoaded() in their static initializer blocks to guarantee that the native library is loaded before any JNI methods are invoked. Calling ensureLoaded() is idempotent because it simply triggers the class's static initializer, which runs exactly once per classloader.

Code Reference

Source Location

java/src/main/java/org/lance/JniLoader.java

Signature

public class JniLoader {
    public static void ensureLoaded();
    // private constructor - not instantiable
    // static native void initLanceLogger();
}

Import

import org.lance.JniLoader;

I/O Contract

Static Methods

Method	Return Type	Description
ensureLoaded()	void	Triggers the static initializer to load the native library if not already loaded

Side Effects

Effect	Description
Native library loading	Extracts and loads lance_jni from the JAR's /nativelib path
Logger initialization	Calls initLanceLogger() to set up the Rust logging subsystem

Usage Examples

import org.lance.JniLoader;

// Ensure the native library is loaded before using Lance APIs
JniLoader.ensureLoaded();

// Typically used in a static initializer block of another class:
public class MyLanceClient {
    static {
        JniLoader.ensureLoaded();
    }

    // ... JNI-dependent code
}

// Control Rust log level via environment variable:
// export LANCE_LOG=debug
// export LANCE_LOG=info

Related Pages

• Lance_format_Lance_Java_Compaction - Calls JniLoader.ensureLoaded() before native compaction methods
• Lance_format_Lance_Java_DatasetDelta - Calls JniLoader.ensureLoaded() for delta computation natives
• Lance_format_Lance_Java_DatasetDeltaBuilder - Calls JniLoader.ensureLoaded() for delta builder natives