feat(bindings/java): add OperatorReader and ReaderOptions

[jihuayu]

Which issue does this PR close?

Closes #8252.

Rationale for this change

Expose the OperatorReader and ReaderOptions abstractions from the Rust core in the Java binding.

What changes are included in this PR?

• Add Operator.createReader(...), OperatorReader, and ReaderOptions, allowing a reader to be configured and then used either for independent range reads or to create an input stream. gap is used by Reader::fetch to merge multiple ranges. Since Java does not currently expose this API, this option is not included.

• Rename the internal Reader used by OperatorInputStream to NativeIterator, and update the corresponding JNI names accordingly, to distinguish it from the newly introduced OperatorReader. This type and its related native methods are private implementation details, so the rename does not affect user code.

• Explicitly throw IllegalStateException when reading from a closed stream, and synchronize close() with read() to prevent the native iterator from being released while a read is in progress, which could otherwise result in invalid memory access.

Are there any user-facing changes?

Yes. Callers can use OperatorReader Now.

Breaking changes

None

AI Usage Statement

• Harness: Codex desktop. Model: GPT-6. For code implementation and validation.

[Xuanwo]

ReadOptions overlaps ReaderOptions. It seems we should just accept ReaderOptions here?

[jihuayu]

Hi @Xuanwo

I see. Yeah, this abstraction isn’t quite right.

I looked more closely into the Java binding, the Rust core, and the history of these APIs.

It seems that Java's current ReadOptions is a legacy binding-specific abstraction introduced before RFC-6213, rather than a direct counterpart of the core ReadOptions. This makes the current read/stream API a bit awkward once ReaderOptions is introduced.

The parameter here should be ReaderOptions, but it is currently named ReadOptions. I need to think about how to correct the API semantics while preserving backward compatibility.

[jihuayu]

Hi @Xuanwo. I finally figured out this code abstraction, and I hope this is what you had in mind.

In this PR, we introduce ReaderOptions. After that, I’ll start working on migrating ReadOptions.