Implementation:Risingwavelabs Risingwave Binding

Property	Value
Component	Java Binding
Language	Java
Source File	java/java-binding/src/main/java/com/risingwave/java/binding/Binding.java
Lines	130
Package	com.risingwave.java.binding
License	Apache 2.0

Overview

Binding is the central JNI binding class that declares all native methods bridging Java to the Rust risingwave_java_binding library. It serves as the fundamental JNI interface connecting all Java connector and binding code to the RisingWave Rust engine.

The class loads the native library from a JAR resource using JarJniLoader at class initialization time, unless the is_embedded_connector system property is set to true (in which case the library is assumed to already be loaded by the embedding process). It declares native methods organized into several categories: iterator operations (row value access, cursor advancement, lifecycle), stream chunk management, CDC source channel communication, sink writer/coordinator stream operations, tracing integration, and object store access.

Code Reference

Source Location

java/java-binding/src/main/java/com/risingwave/java/binding/Binding.java

Signature

public class Binding {
    // Library loading
    static { /* loads risingwave_java_binding via JarJniLoader */ }
    static void ensureInitialized();

    // Tracing
    public static native void tracingSlf4jEvent(
            String threadName, String name, int level, String message, String stackTrace);
    public static native boolean tracingSlf4jEventEnabled(int level);

    // Vnode configuration
    public static native int defaultVnodeCount();

    // Iterator lifecycle
    static native long iteratorNewStreamChunk(long pointer);
    static native boolean iteratorNext(long pointer);
    static native void iteratorClose(long pointer);

    // Stream chunk management
    static native long newStreamChunkFromPayload(byte[] streamChunkPayload);
    static native long newStreamChunkFromPretty(String str);
    static native void streamChunkClose(long pointer);

    // Iterator value accessors
    static native byte[] iteratorGetKey(long pointer);
    static native int iteratorGetOp(long pointer);
    static native boolean iteratorIsNull(long pointer, int index);
    static native short iteratorGetInt16Value(long pointer, int index);
    static native int iteratorGetInt32Value(long pointer, int index);
    static native long iteratorGetInt64Value(long pointer, int index);
    static native float iteratorGetFloatValue(long pointer, int index);
    static native double iteratorGetDoubleValue(long pointer, int index);
    static native boolean iteratorGetBooleanValue(long pointer, int index);
    static native String iteratorGetStringValue(long pointer, int index);
    static native java.time.LocalDateTime iteratorGetTimestampValue(long pointer, int index);
    static native java.time.OffsetDateTime iteratorGetTimestamptzValue(long pointer, int index);
    static native java.math.BigDecimal iteratorGetDecimalValue(long pointer, int index);
    static native java.time.LocalTime iteratorGetTimeValue(long pointer, int index);
    static native java.time.LocalDate iteratorGetDateValue(long pointer, int index);
    static native String iteratorGetIntervalValue(long pointer, int index);
    static native String iteratorGetJsonbValue(long pointer, int index);
    static native byte[] iteratorGetByteaValue(long pointer, int index);
    static native Object iteratorGetArrayValue(long pointer, int index, Class<?> clazz);

    // Object store operations
    public static native void initObjectStoreForTest(String stateStoreUrl, String dataDirectory);
    public static native void putObject(String object, byte[] data);
    public static native String getObjectStoreType();
    public static native void deleteObjects(String dir);
    public static native byte[] getObject(String object);
    public static native String[] listObject(String dir);

    // CDC source channel
    public static native boolean sendCdcSourceMsgToChannel(long channelPtr, byte[] msg);
    public static native boolean sendCdcSourceErrorToChannel(long channelPtr, String errorMsg);
    public static native void cdcSourceSenderClose(long channelPtr);

    // Sink writer stream
    public static native JniSinkWriterStreamRequest recvSinkWriterRequestFromChannel(long channelPtr);
    public static native boolean sendSinkWriterResponseToChannel(long channelPtr, byte[] msg);
    public static native boolean sendSinkWriterErrorToChannel(long channelPtr, String msg);

    // Sink coordinator stream
    public static native byte[] recvSinkCoordinatorRequestFromChannel(long channelPtr);
    public static native boolean sendSinkCoordinatorResponseToChannel(long channelPtr, byte[] msg);
}

Import

import com.risingwave.java.binding.Binding;
// Also requires at runtime:
import io.questdb.jar.jni.JarJniLoader;

I/O Contract

Inputs

• Native pointers (long): Iterator pointers, stream chunk pointers, and channel pointers passed to most methods. These are opaque handles to Rust-side objects.
• Column index (int): Zero-based column index for value accessor methods.
• Serialized payloads (byte[]): Protobuf-serialized messages for stream chunks, CDC source messages, sink writer responses, and sink coordinator responses.
• String parameters: State store URLs, data directories, object keys, pretty-print format strings, error messages, and thread/tracing info.
• Class (Class<?>): Element type class for array value extraction.

Outputs

• Iterator operations: iteratorNext returns boolean indicating whether more rows exist. iteratorNewStreamChunk returns a native pointer to a new iterator.
• Value accessors: Return typed Java values (short, int, long, float, double, boolean, String, LocalDateTime, OffsetDateTime, BigDecimal, LocalTime, LocalDate, byte[], Object).
• Channel operations: sendCdcSourceMsgToChannel, sendSinkWriterResponseToChannel, etc. return boolean indicating success.
• Object store operations: getObject returns byte[], listObject returns String[], getObjectStoreType returns String.
• Stream chunk creation: newStreamChunkFromPayload and newStreamChunkFromPretty return native pointers (long).

Side Effects

• Native library loading: The static initializer loads the risingwave_java_binding native library from the JAR classpath when the class is first referenced.
• Native resource allocation: Methods like iteratorNewStreamChunk, newStreamChunkFromPayload, and newStreamChunkFromPretty allocate native resources that must be released via corresponding close methods.
• Object store I/O: putObject, deleteObjects, and getObject perform actual storage operations.

Usage Examples

Initializing the binding

// Ensure the native library is loaded (triggers static initializer if not already loaded)
Binding.ensureInitialized();

Using iterator value accessors (internal usage pattern)

// These are typically called through BaseRow subclasses, not directly
boolean isNull = Binding.iteratorIsNull(pointer, 0);
if (!isNull) {
    int value = Binding.iteratorGetInt32Value(pointer, 0);
    String name = Binding.iteratorGetStringValue(pointer, 1);
}

Sending CDC source events

// Send a serialized CDC message through the channel
boolean success = Binding.sendCdcSourceMsgToChannel(channelPtr, serializedMessage);
if (!success) {
    Binding.sendCdcSourceErrorToChannel(channelPtr, "Failed to process CDC event");
}

Object store operations (test usage)

Binding.initObjectStoreForTest("hummock+memory", "/tmp/data");
Binding.putObject("path/to/object", data);
byte[] retrieved = Binding.getObject("path/to/object");
String[] listing = Binding.listObject("path/to/");

Related Pages

• BaseRow - Base row class that delegates all typed accessors to Binding native methods
• HummockIterator - Hummock storage iterator using Binding iterator methods
• StreamChunk - StreamChunk wrapper using Binding stream chunk methods
• StreamChunkIterator - StreamChunk row iterator using Binding iterator methods
• CdcSourceChannel - CDC source channel using Binding CDC channel methods
• JniSinkWriterStreamRequest - Sink writer request using Binding sink writer methods