[milyin]

Umbrella PR for rebuilding zenoh-java on top of the generated JNI/Kotlin bindings
(zenoh-flat-jni, produced by prebindgen from
zenoh-flat), replacing the hand-written
zenoh-jni Rust crate and the io.zenoh.jni adapter layer on top of it. This is the
zenoh-java counterpart of eclipse-zenoh/zenoh-kotlin#669 — both SDKs converge on the
same shared bindings tier:

zenoh (Rust)
  └─ zenoh-flat            flat #[prebindgen]-annotated Rust API
       └─ zenoh-flat-jni   generated JNI externs + Kotlin classes (prebindgen JniGen)
            └─ zenoh-java  Java-compatible Kotlin SDK wrapper (this repo)

The zenoh-jni crate (18 files, ~7.8k lines) and every JNI*.kt adapter are deleted;
this repo keeps the public Java-facing SDK plus three small adapter files
(FlatCallbacks.kt, JNIErrorHandlers.kt, JavaTypeSerde.kt). No Rust is built here
any more.

Throughput

Receiver-style generated bindings (#481), release benchmark, subscriber median msg/s,
8 rounds × 100,000 messages per point:

Payload	upstream main	flat JNI	change
8 B	485,085	869,716	+79.3%
64 B	461,949	847,465	+83.5%
1 KiB	407,366	657,009	+61.3%
8 KiB	223,830	249,825	+11.6%

Error model

The generated bindings never throw across JNI: a fallible wrapper takes trailing
error-sink callbacks and returns the sink's value on failure. zenoh-java's public API
is exception-based, so the two shared handlers in JNIErrorHandlers.kt throw ZError
straight from the sink and the SDK needs no try/catch layer at all.

The protocol has two independent channels: onBindingError (JniErrorHandler —
binding-layer failures such as UTF-8 decode or a closed handle) and onError (the typed
domain ErrorHandler, carrying the decomposed zenoh message); an infallible wrapper
takes only the first. Both handlers bind the generated interface's out R to Nothing,
so one instance each satisfies every wrapper regardless of return type.

Callbacks are value-decomposed: a Sample, Query, Hello or Reply arrives as
its leaves in one JNI crossing, with no per-field accessor calls.

Encoding and key expressions as values

Encoding is its (id, schema) pair — a plain immutable JVM value. The id↔name
table and Zenoh's parse/render rules live in the shared tier (EncodingCodec in
zenoh-flat-jni, correspondence-tested against the native implementation), leaving a thin
facade here. This removed a per-message native leak.

Sends are shaped to minimize JNI crossings: the predefined constants are value-only (a
send carries just their id, inside the send call); a custom schema-carrying encoding is
born with a native handle at construction — the one crossing — and re-sends that handle
as a bare jlong; a publisher's default encoding is set natively at declare, so plain
puts carry no encoding data at all. Received encodings are always value-only, since
delivering a handle per message measurably cost more than the schema re-decode it saved.

Symmetrically, a KeyExpr holds a native handle only when it was declared on a
session; every other key expression is a validated string, rebuilt Rust-side inside the
call that needs it. Handle release is GC-managed by a shared Cleaner in the generated
tier.

Serialization

zSerialize/zDeserialize no longer cross JNI. JavaTypeSerde.kt maps a Guava
TypeToken's java.lang.reflect.Type to a SerializationCodec.SerdeType and the
shared pure-Kotlin codec in zenoh-flat-jni does the encoding — byte-identical to the
native serializer (correspondence-tested upstream). Kotlin-only unsigned value classes
and Pair/Triple erase in Java reflection and remain unexpressible here, as before.

Public API changes

Source-breaking, all tracking zenoh/zenoh-flat semantics:

• Timestamp — ReplyOptions.timeStamp and Sample.timestamp carry
  io.zenoh.time.Timestamp (the (ntp64, id) pair, mirroring zenoh::time::Timestamp)
  instead of commons-net's TimeStamp. The old JNI layer supplied the missing half with
  ID::rand(); a reply now carries the replying session's real id, and a received sample
  surfaces the sender's, previously discarded. Callers write
  options.setTimeStamp(Timestamp.ofNtp64(ntp64, session.info().zid())). commons-net
  drops out of the library's dependencies (tests and the ZQueryable example still use
  it as an NTP64 clock).
• Parameters — a thin facade over the shared string-backed implementation
  (Rust parameters.rs semantics): values are no longer percent-decoded, parsing is
  infallible, duplicate keys are accepted with first-match-wins get, and toString
  round-trips verbatim. Correspondence-tested against the native oracle.
• Config.fromJson parses via JSON5 (of which JSON is a subset — every input
  accepted before parses to the same config); the invented config_new_from_json entry
  point is gone.
• A sample's source and a reply's replier arrive as whole SourceInfo /
  EntityGlobalId values, so optionality lives on the value rather than on a leading zid
  leaf.
• An encoding schema is raw bytes on the wire: it is encoded at the boundary on send and
  decoded lossily on receive, rather than throwing on a received message.

Build, CI and release

• No Rust toolchain, NDK cross-compilation or cargoBuild wiring in this repo; the
  native library ships with org.eclipse.zenoh:zenoh-flat-jni.
• The dependency resolves from Maven Central at the version in gradle.properties
  (zenohFlatJniVersion). -PuseLocalFlatJni=true substitutes a sibling checkout
  through a Gradle composite build for coordinated development; it is off by default and
  must stay off for a release.
• publish-jvm.yml and publish-android.yml are merged into one publish.yml, so both
  coordinates come from a single Gradle invocation and share one staging repository —
  released together or not at all. bump-and-tag.bash knows the zenoh-flat-jni version
  and refuses a snapshot on a live run. See PUBLISHING.md.
• CI checks out sibling zenoh-flat-jni / zenoh-flat at pinned commits, builds through
  the composite build, and gates on the linked crate's fmt/clippy/feature-leak checks;
  prebindgen resolves from crates.io. Pins are bumped as the upstream PRs land.

Constituent PRs

PR	Scope
#481	Use receiver-style zenoh-flat-jni bindings (generated Session/Query/Publisher methods, split key-expr overloads, de-prefixed callback names)
#484	Encoding/ZenohId.toString as pure JVM values over the shared EncodingCodec; publisher default encoding set natively at declare
#485	Encoding: native handle where it is born, value where it is cheapest
#488	Received preset encodings are value-only end to end
#489	Receive path goes value-only: KeyExpr string-backed except declared, Encoding always (id, schema)
#490	Align lifecycle KDoc with actual GC management
#491	Session.undeclare detaches the key-expr handle even when the native undeclare fails
#492	Parameters becomes a facade over the shared string-backed implementation
#495	Migrate to the split error-handler API
#496	Serialize via the shared pure-Kotlin SerializationCodec (no JNI)
93c6f05	Realign with zenoh-flat HEAD; a timestamp carries its clock's id (direct commit)
#511	CI: build zenoh-flat-jni against published prebindgen
#514	Release preparation: repair the release path, document publishing

Process

This PR stays draft while the transition is in progress. Individual changes land as
reviewable PRs targeting the zenoh-flat-transition branch; this PR accumulates them
and merges to main as a whole. Upstream companion PRs (prebindgen → zenoh-flat →
zenoh-flat-jni) merge first; the zenoh-java PR then pins the exact upstream commits in CI
and merges once green. This description is the branch's living record — the
ZENOH_FLAT_TRANSITION.md bookkeeping file it replaced is removed by #515.

🤖 Generated with Claude Code

[milyin]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved in 9a5a1ea.

[milyin]

Review of the branch as of 9a5a1ea

Read the whole diff vs main (98 files, +2,365 / −10,970). The substance holds up: the
two shared throwing handlers are threaded consistently at every generated call site, the
consuming-vs-borrowing key-expr split is used correctly, the Encoding three-way send
shaping (constant → id only, custom → born handle, received → (id, schema)) is
coherent with the receive path, and the handle-lifecycle tests added along the way
(EncodingHandleTest, KeyExprHandleTest, PublisherEncodingTest,
QueryParametersTest) cover exactly the places where ownership was easy to get wrong.
The branch is up to date with main and merges cleanly. No correctness objections.

Three loose ends, none blocking:

1. ZENOH_FLAT_TRANSITION.md is well out of date. Its constituent-PR table stops at
   Encoding as a pure JVM value + native publisher default + pinned per-put override #484 ("in progress") plus "shared-parameters — open", so it misses Encoding: native handle where it is born, value where it is cheapest #485, Received preset encodings are value-only end to end #488, Receive path goes value-only: KeyExpr string-backed except declared, Encoding always (id, schema) #489,
   docs: align lifecycle KDoc with actual GC management #490, Parameters becomes a thin facade over the shared string-backed implementation #492, Migrate to the split error-handler API (zenoh-flat-jni #45) #495, Serialize via the shared pure-Kotlin SerializationCodec (no JNI) #496, CI: build zenoh-flat-jni against published prebindgen #511 and Release preparation: repair the release path and document publishing #514, and the realignment commit. Its links still
   point at the old ZettaScaleLabs/zenoh-flat{,-jni} forks (lines 19–20, 29, 31, 34)
   while CI already checks out eclipse-zenoh. Either refresh it or drop it at merge
   time — it is meant to be removed anyway.

2. rust-toolchain.toml looks like dead weight. No Rust is built in this repo any
   more. It pins 1.97.1, while CI explicitly does rustup component add rustfmt clippy --toolchain 1.93.0 and runs every cargo command inside the sibling zenoh-flat-jni
   checkout, where that repo's own toolchain file applies. zenoh-kotlin deleted its copy
   in the equivalent transition; keeping a stale pin here can only mislead.

3. release.yml still runs publish-github. Withdrawn — eclipse-zenoh/ci/publish-crates-github runs gh release create --generate-notes first and only then uploads matching build artifacts. The release-creating half is still wanted here; the artifact half simply finds nothing. PUBLISHING.md already describes it correctly. Keep the job.

Findings 1 and 2 are fixed in #515.

Observation, not a defect: CI here gates on cargo fmt --check, cargo clippy -D warnings and the feature-leak cargo test --no-default-features against the pinned
zenoh-flat-jni checkout. Those are zenoh-flat-jni's own CI checks, and the pin is always
a commit that already passed them upstream; zenoh-kotlin's workflow just builds the
sibling checkout. Keeping them is defensible as a belt-and-braces gate, but it is
duplicated work on every run of this repo's matrix.

🤖 Generated with Claude Code

[milyin]

Review of 102fb8c

I reviewed the complete branch against main (including the final scaffolding removal), traced the generated JNI ownership contracts at the commits pinned by CI, and generated the JVM/Android publication POMs locally. The migration itself is internally consistent, but I found two release-blocking issues:

1. [P1] Plain Maven consumers do not receive zenoh-flat-jni-jvm. commonMain declares implementation("org.eclipse.zenoh:zenoh-flat-jni:$zenohFlatJniVersion"), and the generated zenoh-java JVM POM therefore depends on the KMP root coordinate org.eclipse.zenoh:zenoh-flat-jni:1.9.0. At merged zenoh-flat-jni KMP commit 9f6e5e9, that root coordinate's POM contains only kotlin-stdlib-common; it does not depend on zenoh-flat-jni-jvm. Gradle consumers happen to work because Gradle reads the root .module metadata and selects the JVM variant, but Maven ignores Gradle module metadata. A Maven application depending on zenoh-java will consequently have neither the generated io.zenoh.jni.* classes nor the desktop native libraries at runtime. The published JVM POM needs a direct zenoh-flat-jni-jvm dependency (and the Android POM the Android artifact), or an equivalent publication-time mapping. A small Maven consumer test against the locally published artifacts would catch this and the currently documented “no consumer test” gap.

2. [P1] Dropping an unread received payload leaks its native allocation permanently. ZBytes.fromHandle stores each received native handle, but cleanup happens only when bytes is read. The generated io.zenoh.jni.bytes.ZBytes at the CI-pinned commit extends plain NativeHandle, not GcNativeHandle, and the SDK's ZBytes exposes no close/discard operation. Therefore a perfectly normal subscriber such as { sample -> count.incrementAndGet() }, or one that inspects only key/QoS metadata, leaks one native ZBytes box/buffer per message (plus an attachment when present) after the Sample becomes unreachable. The KDoc explicitly acknowledges that allocation is retained, but there is no user action available after dropping the sample, so this is unbounded native memory growth rather than delayed reclamation. Please restore a reclamation path—eager extraction, a GC backstop, or another lifecycle design that guarantees unread handles are eventually freed—and add a pressure test that discards payloads.

The current GitHub checks exercise the Gradle/composite-build path, so neither issue is covered by the green JVM suite.

— Codex (GPT-5)