Implementation:Risingwavelabs Risingwave HummockIterator

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

Overview

HummockIterator is a Java wrapper for iterating over data stored in RisingWave's Hummock storage engine. It provides a next()/close() pattern over a native Rust iterator, enabling Java code to read directly from Hummock storage via JNI.

The class creates a native Hummock iterator from a serialized ReadPlan protobuf message. On each call to next(), it advances the native iterator via Binding.iteratorNext and returns a KeyedRow instance representing the current row, or null when no more rows are available. The class implements AutoCloseable to ensure the native iterator is properly released.

A static initializer block calls Binding.ensureInitialized() to guarantee that the JNI native library is loaded before any Hummock iterator is created.

Code Reference

Source Location

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

Signature

public class HummockIterator implements AutoCloseable {
    private final long pointer;
    private boolean isClosed;

    // Native method
    private static native long iteratorNewHummock(byte[] readPlan);

    public HummockIterator(ReadPlan readPlan);
    public KeyedRow next();

    @Override
    public void close();
}

Import

import com.risingwave.java.binding.HummockIterator;
// Required for construction:
import com.risingwave.proto.JavaBinding.ReadPlan;

I/O Contract

Inputs

• readPlan (ReadPlan): A protobuf ReadPlan message that specifies what data to read from Hummock storage. This is serialized to bytes via toByteArray() and passed to the native iteratorNewHummock method.

Outputs

• next() returns KeyedRow: The next row from the Hummock iterator, or null when all rows have been consumed. KeyedRow extends BaseRow and provides access to both the key bytes and typed column values.

Side Effects

• Native resource allocation: The constructor allocates a native Rust iterator via iteratorNewHummock. This iterator maintains references to Hummock SST files and internal state.
• Native resource release: close() calls Binding.iteratorClose(pointer) to free the native iterator. The isClosed flag prevents double-close.
• Storage I/O: Each call to next() may trigger reads from Hummock storage (SST files, block cache) on the Rust side.

Usage Examples

Reading rows from Hummock storage

import com.risingwave.proto.JavaBinding.ReadPlan;

ReadPlan readPlan = ReadPlan.newBuilder()
        // ... configure read plan fields ...
        .build();

try (HummockIterator iter = new HummockIterator(readPlan)) {
    KeyedRow row;
    while ((row = iter.next()) != null) {
        byte[] key = row.getKey();
        int id = row.getInt(0);
        String name = row.getString(1);
        // Process row data...
    }
}
// Native iterator is automatically closed via AutoCloseable

Related Pages

• Binding - Declares iteratorNext and iteratorClose native methods used by HummockIterator
• BaseRow - Base class for row data access; KeyedRow (returned by HummockIterator) extends BaseRow
• StreamChunkIterator - Analogous iterator for StreamChunk data (vs. Hummock storage data)