Implementation:Risingwavelabs Risingwave StreamChunk

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

Overview

StreamChunk is a Java wrapper for a native Rust StreamChunk, representing a batch of streaming rows with associated operation types (insert, delete, update). It is the core data structure for passing streaming row batches between the Rust engine and Java sink connectors.

The class manages a native pointer to a Rust-side StreamChunk and supports four creation modes:

1. From serialized payload: Deserializes a StreamChunk from a protobuf byte array.
2. From owned pointer: Takes ownership of a native pointer (will free on close).
3. From reference pointer: Borrows a native pointer (will not free on close).
4. From pretty-print string: Parses a human-readable table format string (used primarily in tests).

The class implements AutoCloseable. On close, it only releases the native resource if the chunk is owned (not borrowed).

Code Reference

Source Location

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

Signature

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

    StreamChunk(long pointer, boolean isOwnedChunk);

    public static StreamChunk fromPayload(byte[] streamChunkPayload);
    public static StreamChunk fromRefPointer(long pointer);
    public static StreamChunk fromOwnedPointer(long pointer);
    public static StreamChunk fromPretty(String str);

    @Override
    public void close();

    long getPointer();
}

Import

import com.risingwave.java.binding.StreamChunk;

I/O Contract

Inputs

• streamChunkPayload (byte[]): A serialized stream chunk payload (protobuf bytes) for fromPayload.
• pointer (long): A native pointer to a Rust-side StreamChunk for fromRefPointer and fromOwnedPointer.
• str (String): A pretty-print format string for fromPretty. Format example: "I I\n + 199 40" where the first line defines column types (I = integer), subsequent lines define operations (+ = insert) and values.

Outputs

• All factory methods return a StreamChunk instance wrapping the native pointer.
• getPointer() returns the underlying native pointer (package-private access).

Side Effects

• Native resource allocation: fromPayload calls Binding.newStreamChunkFromPayload and fromPretty calls Binding.newStreamChunkFromPretty, both allocating native Rust objects.
• Ownership semantics: Only owned chunks are freed on close() via Binding.streamChunkClose(pointer). Reference (borrowed) chunks are not freed, as their lifecycle is managed by the Rust side.
• Double-close protection: The isClosed flag prevents calling streamChunkClose more than once.

Usage Examples

Creating a StreamChunk from a serialized payload

byte[] payload = receiveSinkWriterBatch();
try (StreamChunk chunk = StreamChunk.fromPayload(payload)) {
    // Iterate over rows in the chunk
    try (StreamChunkIterator iter = new StreamChunkIterator(chunk)) {
        StreamChunkRow row;
        while ((row = iter.next()) != null) {
            int op = row.getOp();
            String value = row.getString(0);
            // Process each row...
        }
    }
}

Creating a StreamChunk from a pretty-print string (for testing)

// Create a test chunk with two integer columns, one insert row
try (StreamChunk chunk = StreamChunk.fromPretty("I I\n + 199 40")) {
    try (StreamChunkIterator iter = new StreamChunkIterator(chunk)) {
        StreamChunkRow row = iter.next();
        assert row != null;
        assert row.getInt(0) == 199;
        assert row.getInt(1) == 40;
    }
}

Using a borrowed reference pointer

// Borrow a chunk pointer from a JNI callback (Rust owns the memory)
StreamChunk borrowed = StreamChunk.fromRefPointer(nativeChunkPtr);
// Use the chunk... but do NOT close it (Rust manages the lifecycle)
try (StreamChunkIterator iter = new StreamChunkIterator(borrowed)) {
    // Read rows...
}
// borrowed.close() is safe to call but will not free the native memory

Related Pages

• Binding - Declares native methods newStreamChunkFromPayload, newStreamChunkFromPretty, and streamChunkClose
• StreamChunkIterator - Iterator for traversing rows within a StreamChunk
• JniSinkWriterStreamRequest - Sink writer request that may hold a StreamChunk for zero-copy data passing
• BaseRow - Base class for row access; StreamChunkRow (produced by StreamChunkIterator) extends BaseRow