zerodds-endpoint-java 1.0 — Spec Coverage

Source: docs/specs/zerodds-endpoint-java-1.0.md — the ZeroDDS Java endpoint SDK spec. Reliable-stream contract details in docs/spec-coverage/reliable-endpoint-1.0.en.md. This document covers transport; marshalling is produced by the shared code generator (crates/lang-rules, the Language::Java column) rather than by a Java-specific generator. The former codegen coverage zerodds-xcdr2-java went with crates/idl-java (commit fa2ed8b0a9c).

Implementation:

  • endpoints/java/ZdwEndpoint.java (default package) — XRCE framing (xrceWriteFrame/xrceReadBody), serial framing after Annex C (serialFrame/serialDeframe/fcs16).
  • endpoints/java/Zdw.java (default package) — wire core (Writer/Reader, XCDR2).
  • endpoints/java/org/zerodds/endpoint/ReliableWire.java — reliable wire codec (HEARTBEAT/ACKNACK/WRITE_DATA) + RFC-1982 comparisons.
  • endpoints/java/org/zerodds/endpoint/ReliableSender.java / ReliableReceiver.java — reliable sender/receiver state machine.
  • endpoints/java/org/zerodds/endpoint/AsyncReliableWriter.java — async-decoupled reliable writer (BlockingQueue + drain Thread).
  • crates/endpoint-e2e/tests/java.rs — ping-pong E2E; crates/endpoint-e2e/tests/java_reliable.rs — reliable-stream E2E + latency comparison.
  • endpoints/java/EndpointTest.java — byte-golden for WRITE_DATA/serial/DATA/heartbeat-read/ACKNACK (in the java column of tools/endpoints-gate against the goldens from cargo run -p zerodds-endpoint-golden).

§1 XRCE framing

Spec: §1 — 8-byte XRCE header (session, stream, seq LE, submsg id 0x07 WRITE_DATA, flags, len LE) + body, byte-identical to crates/xrce + endpoints/c; DATA receive path (id 0x09) through the same unwrap; serial framing after Annex C.1 (addresses, length, FCS-16 of RFC 1662).

Repo: endpoints/java/ZdwEndpoint.java — xrceWriteFrame/xrceReadBody, constants SESSION_NOKEY (0x80)/STREAM_BEST_EFFORT (0x01), serialFrame/serialDeframe/fcs16, heartbeatRead, acknackFrame.

Tests: endpoints/java/EndpointTest.java in the java column of tools/endpoints-gate (job integration-endpoints, java EndpointTest "$goldens") against the five golden files generated with zerodds-endpoint-golden (golden_xrce_le.bin, golden_serial_le.bin, golden_data_le.bin, golden_heartbeat_le.bin, golden_acknack_le.bin). Unlike ReliableSelfTest, EndpointTest carries no hardcoded fallback goldens. The SDK’s frame against the decoder of zerodds-xrce: crates/endpoint-e2e/tests/xrce_write_framing.rs::xrce_8_3_5_8_java_endpoint_frames_a_conformant_write_data.

Run on the Linux test host (tools/endpoints-gate, at 8bcb1d00161):

XRCE WRITE_DATA byte-identical (52 bytes)
serial byte-identical
DATA receive: body ok
serial deframe+crc round-trip ok
wrong frameCheck refused
0x7E inside the frame refused
HEARTBEAT parsed: first=1 last=3
ACKNACK byte-identical
appended submessage bounded out
over-long length rejected
truncated header rejected
writer >0xFFFF refused
writer maximal body framed
ALL OK

The framing is also exercised live via xrce_8_3_5_8_java_sync_app_writes_the_ping_and_reads_the_pong/xrce_8_3_5_8_java_async_app_writes_the_ping_and_reads_the_pong (§4).

Status: done

§2 Sync send/recv

Spec: §2 — transport-opaque, no Client object: ZdwEndpoint is stateless; the integrator owns the run loop and calls xrceWriteFrame/xrceReadBody directly against its own transport (a socket or an in-memory queue).

Repo: endpoints/java/ExampleSync.java — in-memory ArrayDeque poll loop, full field decode (Reading{id,value,label}); sync mode in crates/endpoint-e2e/tests/java.rs::MAIN_JAVA_TAIL — blocking DatagramSocket.receive() against the real Rust peer.

Tests: xrce_8_3_5_8_java_sync_app_writes_the_ping_and_reads_the_pong (§4).

Status: done.

§3 Async Reader/Writer

Spec: §3 — a reader Thread drains the transport into a BlockingQueue; the consumer blocks on take(). No dedicated AsyncReader/AsyncWriter class for the plain path (unlike endpoints/go) — the integrator composes it from the stateless ZdwEndpoint framing methods.

Repo: endpoints/java/ExampleAsync.java — reader Thread + LinkedBlockingQueue<byte[]> inbox, full field decode; async mode in crates/endpoint-e2e/tests/java.rs::MAIN_JAVA_TAIL — a reader Thread reads from the real DatagramSocket, the consumer blocks on take().

Tests: xrce_8_3_5_8_java_async_app_writes_the_ping_and_reads_the_pong (§4).

Status: done.

§4 Ping-pong E2E (live)

Spec: §5.1 — a Java app exchanges a typed sample with the shared Rust XRCE peer over a real UDP socket: the generated Ping/Pong codec + the endpoint SDK (ZdwEndpoint), sync and async.

Repo: crates/endpoint-e2e/tests/java.rs — MAIN_JAVA_HEAD (imports and class header) and MAIN_JAVA_TAIL (the run loop, mode sync/async via CLI argument) wrap the members of the generated ZdCodec; split_generated lifts them out of that class, because the generator emits them private static and nothing outside the class could otherwise call them. Compiled against runtime/java (org.zerodds.wire.*) — the former runtime crates/java-omgdds + crates/idl-java/runtime went with the IDL transplant.

Tests: (crates/endpoint-e2e/tests/java.rs, job integration-bindings) - xrce_8_3_5_8_java_sync_app_writes_the_ping_and_reads_the_pong — full stack via blocking DatagramSocket.receive(). - xrce_8_3_5_8_java_async_app_writes_the_ping_and_reads_the_pong — full stack via reader Thread/LinkedBlockingQueue.

Status: done.

§5 Reliable stream — state machine, wire, async writer

Spec: §4 (references reliable-endpoint v1.0 §3/§4) — XRCE reliable stream (stream_id 0x80, §8.4.10/§8.4.11), mirroring the reference crates/xrce/src/reliable.rs: ReliableSender.submit/pendingHeartbeat/ recvAcknack/getInFlight; ReliableReceiver.recvData/drainInOrder/ pendingAcknack/reset. Window 16, receiver buffer 64, heartbeat 500 ms, payload ≤ 65535, RFC-1982 16-bit sequence numbers. Alongside it, the async-decoupled AsyncReliableWriter: the producer enqueues wait-free onto a buffered BlockingQueue (submit/offer), a dedicated drain Thread holds the ReliableSender state and does all the I/O (send, heartbeat, ACKNACK-driven retransmit) — the producer never enters the kernel.

Repo: endpoints/java/org/zerodds/endpoint/ReliableWire.java — writeFrame, heartbeatFrame/parseHeartbeat, acknackFrame/parseAckNack, seqLt/seqGt; ReliableSender, ReliableReceiver; AsyncReliableWriter (ArrayBlockingQueue<byte[]> capacity 4096, drain Thread zdw-reliable-drain, submit/offer/finish/delivered); example app endpoints/java/ExampleReliable.java (a real UDP peer, no in-process stub).

Tests: - endpoints/java/ReliableSelfTest.java in the java column of tools/endpoints-gate (job integration-endpoints) — compiles and runs endpoints/java/ReliableSelfTest.java: 33 check() assertions across 17 test scenarios (sender: monotonic seq, in-flight count, payload-too-large, window-full, heartbeat first/silence/after-500ms, no-heartbeat-when-empty, acknack partial/full clear; receiver: in-order drain, reorder, duplicate dropped, buffer-full, pending-acknack bitmap, reset; in-process end-to-end loss recovery; byte-golden for HEARTBEAT/ACKNACK — hardcoded and, when cargo run -p zerodds-endpoint-golden is available, additionally checked against the generated golden_heartbeat_le.bin/golden_acknack_le.bin). Byte-golden: HeartbeatFrame(1,3) == 80 00 01 00 0b 01 05 00 01 00 03 00 80, AckNackFrame(1,0) == 80 00 01 00 0a 01 05 00 01 00 00 00 80 — identical to the reference goldens (same bytes as endpoints/go). Output: ALL OK. - reliable_5_3_java_samples_arrive_in_order_despite_dropped_datagrams — the peer drops every 3rd sample once; the app the test builds from the Ping the language’s generator writes from the IDL of crates/endpoint-e2e/src/codegen.rs, and AsyncReliableWriter retransmits on ACKNACK; all 12 samples delivered gap-free in order, the test reads every sample by the IDL’s XCDR2 layout (assert_reliable_pings).

Status: done.

§6 Latency — BlockingQueue enqueue vs. inline DatagramSocket.send

Spec: §5.3 — the producer path of AsyncReliableWriter (offer → BlockingQueue push) must be measurably below the inline DatagramSocket.send syscall — the evidence that async write removes syscall latency from the producer path, not that it waits for ACKNACK.

Repo: endpoints/java/ReliableBench.java — 20000 iterations of inline DatagramSocket.send (a real, bound loopback destination socket, never read) vs. 20000 iterations of BlockingQueue.offer (a drain Thread keeps the queue empty, the way AsyncReliableWriter’s real drain thread would), no live peer needed.

Tests: reliable_5_4_java_the_producer_enqueue_costs_less_than_the_inline_send (crates/endpoint-e2e/tests/java_reliable.rs, job integration-bindings): the test checks that the queue-enqueue median stays below the inline-send median. Measured earlier:

producer latency: queue-enqueue median = 84 ns, inline-send median = 5917 ns (70x)

Median over 20000 iterations per path, measured locally (macOS, not a Linux run) — the order of magnitude matches endpoints/go’s Linux-verified 20–25 ns / 4360 ns (~175–220×); the absolute value is machine-/load-dependent, the ratio (enqueue well below the syscall) is the evidence.

Status: done.


Audit status

6 done / 0 partial / 0 open / 0 blocked / 0 n/a (informative).

Test run: in CI, crate tier and pillar jobs; the cited tests with the latest result of each job in the pipelines 8501 to 9053 of main (python3 ci/coverage_results.py --document zerodds-endpoint-java-1.0.md):

  • python3 ci/run_integration.py integration-bindings (job integration-bindings) — 5 tests green.

5 cited tests green, 0 not green.

Open items: none.

zerodds-endpoint-java 1.0 — Spec-Coverage

Quelle: docs/specs/zerodds-endpoint-java-1.0.md — ZeroDDS Java Endpoint-SDK-Spec. Reliable-Stream-Kontraktdetails in docs/spec-coverage/reliable-endpoint-1.0.md. Hier der Transport; das Marshalling erzeugt der gemeinsame Codegen (crates/lang-rules, Spalte Language::Java) und nicht mehr ein Java-eigener Generator. Die frühere Codegen-Coverage zerodds-xcdr2-java ist mit crates/idl-java entfallen (Commit fa2ed8b0a9c).

Implementation:

  • endpoints/java/ZdwEndpoint.java (Default-Package) — XRCE-Framing (xrceWriteFrame/xrceReadBody), serielles Framing nach Annex C (serialFrame/serialDeframe/fcs16).
  • endpoints/java/Zdw.java (Default-Package) — Wire-Core (Writer/Reader, XCDR2).
  • endpoints/java/org/zerodds/endpoint/ReliableWire.java — reliable Wire-Codec (HEARTBEAT/ACKNACK/WRITE_DATA) + RFC-1982-Vergleiche.
  • endpoints/java/org/zerodds/endpoint/ReliableSender.java / ReliableReceiver.java — reliable Sender-/Receiver-State-Machine.
  • endpoints/java/org/zerodds/endpoint/AsyncReliableWriter.java — async-entkoppelter reliable Writer (BlockingQueue + Drain-Thread).
  • crates/endpoint-e2e/tests/java.rs — Ping-Pong-E2E; crates/endpoint-e2e/tests/java_reliable.rs — reliable-Stream-E2E + Latenz-Vergleich.
  • endpoints/java/EndpointTest.java — Byte-Golden für WRITE_DATA/serial/DATA/HEARTBEAT-Read/ACKNACK (in der Spalte java von tools/endpoints-gate gegen die Goldens aus cargo run -p zerodds-endpoint-golden).

§1 XRCE-Framing

Spec: §1 — 8-Byte-XRCE-Header (session, stream, seq LE, submsg id 0x07 WRITE_DATA, flags, len LE) + Body, byte-identisch zu crates/xrce + endpoints/c; DATA-Empfangspfad (id 0x09) über denselben Unwrap; serielles Framing nach Annex C.1 (Adressen, Länge, FCS-16 nach RFC 1662).

Repo: endpoints/java/ZdwEndpoint.java — xrceWriteFrame/xrceReadBody, Konstanten SESSION_NOKEY (0x80)/STREAM_BEST_EFFORT (0x01), serialFrame/serialDeframe/fcs16, heartbeatRead, acknackFrame.

Tests: endpoints/java/EndpointTest.java in der Spalte java von tools/endpoints-gate (Job integration-endpoints, java EndpointTest "$goldens") gegen die fünf mit zerodds-endpoint-golden erzeugten Golden-Dateien (golden_xrce_le.bin, golden_serial_le.bin, golden_data_le.bin, golden_heartbeat_le.bin, golden_acknack_le.bin). Anders als ReliableSelfTest trägt EndpointTest keine fest verdrahteten Ersatz-Goldens. Der Rahmen des SDK gegen den Decoder von zerodds-xrce: crates/endpoint-e2e/tests/xrce_write_framing.rs::xrce_8_3_5_8_java_endpoint_frames_a_conformant_write_data.

Lauf auf dem Linux-Testhost (tools/endpoints-gate, Stand 8bcb1d00161):

XRCE WRITE_DATA byte-identical (52 bytes)
serial byte-identical
DATA receive: body ok
serial deframe+crc round-trip ok
wrong frameCheck refused
0x7E inside the frame refused
HEARTBEAT parsed: first=1 last=3
ACKNACK byte-identical
appended submessage bounded out
over-long length rejected
truncated header rejected
writer >0xFFFF refused
writer maximal body framed
ALL OK

Das Framing wird zusätzlich live über xrce_8_3_5_8_java_sync_app_writes_the_ping_and_reads_the_pong/xrce_8_3_5_8_java_async_app_writes_the_ping_and_reads_the_pong (§4) geübt.

Status: done

§2 sync send/recv

Spec: §2 — transport-opak, kein Client-Objekt: ZdwEndpoint ist zustandslos; der Integrator besitzt den Run-Loop und ruft xrceWriteFrame/xrceReadBody direkt gegen seinen eigenen Transport (Socket oder In-Memory-Queue) auf.

Repo: endpoints/java/ExampleSync.java — In-Memory-ArrayDeque-Poll-Loop, volles Feld-Decode (Reading{id,value,label}); sync-Modus in crates/endpoint-e2e/tests/java.rs::MAIN_JAVA_TAIL — blockierendes DatagramSocket.receive() gegen den echten Rust-Peer.

Tests: xrce_8_3_5_8_java_sync_app_writes_the_ping_and_reads_the_pong (§4).

Status: done.

§3 async Reader/Writer

Spec: §3 — Reader-Thread drainiert den Transport in eine BlockingQueue, Consumer blockiert auf take(); keine dedizierte AsyncReader/AsyncWriter-Klasse für den Plain-Pfad (anders als endpoints/go) — der Integrator komponiert sie aus den zustandslosen ZdwEndpoint-Framing-Methoden.

Repo: endpoints/java/ExampleAsync.java — Reader-Thread + LinkedBlockingQueue<byte[]>-Inbox, volles Feld-Decode; async-Modus in crates/endpoint-e2e/tests/java.rs::MAIN_JAVA_TAIL — Reader-Thread liest vom echten DatagramSocket, Consumer blockiert auf take().

Tests: xrce_8_3_5_8_java_async_app_writes_the_ping_and_reads_the_pong (§4).

Status: done.

§4 Ping-Pong-E2E (live)

Spec: §5.1 — eine Java-App tauscht mit dem geteilten Rust-XRCE-Peer über einen echten UDP-Socket ein typisiertes Sample aus: generierter Ping/Pong-Codec + Endpoint-SDK (ZdwEndpoint), sync und async.

Repo: crates/endpoint-e2e/tests/java.rs — MAIN_JAVA_HEAD (Imports und Klassenkopf) und MAIN_JAVA_TAIL (Run-Loop, Modus sync/async per CLI-Argument) umschließen die Member des generierten ZdCodec; split_generated hebt sie aus der Klasse, weil der Generator sie private static schreibt und sie sonst von außen nicht erreichbar wären. Kompiliert gegen runtime/java (org.zerodds.wire.*) — die frühere Runtime crates/java-omgdds + crates/idl-java/runtime ist mit dem IDL-Transplantat entfallen.

Tests: (crates/endpoint-e2e/tests/java.rs, Job integration-bindings) - xrce_8_3_5_8_java_sync_app_writes_the_ping_and_reads_the_pong — voller Stack über blockierendes DatagramSocket.receive(). - xrce_8_3_5_8_java_async_app_writes_the_ping_and_reads_the_pong — voller Stack über Reader-Thread/LinkedBlockingQueue.

Status: done.

§5 Reliable Stream — State-Machine, Wire, Async-Writer

Spec: §4 (verweist auf reliable-endpoint v1.0 §3/§4) — XRCE reliable Stream (stream_id 0x80, §8.4.10/§8.4.11), spiegelt die Referenz crates/xrce/src/reliable.rs: ReliableSender.submit/pendingHeartbeat/ recvAcknack/getInFlight; ReliableReceiver.recvData/drainInOrder/ pendingAcknack/reset. Fenster 16, Receiver-Buffer 64, Heartbeat 500 ms, Payload ≤ 65535, RFC-1982 16-bit Sequenznummern. Dazu der async-entkoppelte AsyncReliableWriter: der Producer enqueued wait-free in eine gepufferte BlockingQueue (submit/offer), ein dedizierter Drain-Thread hält den ReliableSender-State und macht die gesamte I/O (senden, Heartbeat, ACKNACK-getriebenes Retransmit) — der Producer geht nie in den Kernel.

Repo: endpoints/java/org/zerodds/endpoint/ReliableWire.java — writeFrame, heartbeatFrame/parseHeartbeat, acknackFrame/parseAckNack, seqLt/seqGt; ReliableSender, ReliableReceiver; AsyncReliableWriter (ArrayBlockingQueue<byte[]> Kapazität 4096, Drain-Thread zdw-reliable-drain, submit/offer/finish/delivered); Beispiel-App endpoints/java/ExampleReliable.java (echter UDP-Peer, kein In-Process-Stub).

Tests: - endpoints/java/ReliableSelfTest.java in der Spalte java von tools/endpoints-gate (Job integration-endpoints) — kompiliert und läuft endpoints/java/ReliableSelfTest.java: 33 check()-Assertionen über 17 Testszenarien (Sender: monotone seq, in-flight count, payload-too-large, window-full, heartbeat first/silence/after-500ms, no-heartbeat-when-empty, acknack partial/full clear; Receiver: in-order drain, reorder, duplicate dropped, buffer-full, pending-acknack-Bitmap, reset; End-to-End Loss-Recovery in-process; Byte-Golden für HEARTBEAT/ACKNACK — hardcoded und, wenn cargo run -p zerodds-endpoint-golden verfügbar ist, zusätzlich gegen die generierten golden_heartbeat_le.bin/ golden_acknack_le.bin geprüft). Byte-Golden: HeartbeatFrame(1,3) == 80 00 01 00 0b 01 05 00 01 00 03 00 80, AckNackFrame(1,0) == 80 00 01 00 0a 01 05 00 01 00 00 00 80 — identisch zu den Referenz-Goldens (gleiche Bytes wie endpoints/go). Ausgabe: ALL OK. - reliable_5_3_java_samples_arrive_in_order_despite_dropped_datagrams — Peer dropt jedes 3. Sample einmalig; die App, die der Test aus dem Ping, den der Generator der Sprache aus der IDL von crates/endpoint-e2e/src/codegen.rs schreibt, und AsyncReliableWriter baut, retransmittet auf ACKNACK; alle 12 Samples lückenlos in Reihenfolge geliefert, der Test liest jedes Sample nach dem XCDR2-Layout der IDL (assert_reliable_pings).

Status: done.

§6 Latenz — BlockingQueue-Enqueue vs. inline DatagramSocket.send

Spec: §5.3 — der Producer-Pfad des AsyncReliableWriter (offer → BlockingQueue-Push) muss messbar unter dem inline DatagramSocket.send-Syscall liegen — der Beleg, dass Async-Write die Syscall-Latenz aus dem Producer-Pfad nimmt, nicht das Warten auf ACKNACK.

Repo: endpoints/java/ReliableBench.java — 20000 Iterationen inline DatagramSocket.send (echter, gebundener Loopback-Zielsocket, nie gelesen) vs. 20000 Iterationen BlockingQueue.offer (Drain-Thread hält die Queue leer, wie AsyncReliableWriters echter Drain-Thread), kein Live-Peer nötig.

Tests: reliable_5_4_java_the_producer_enqueue_costs_less_than_the_inline_send (crates/endpoint-e2e/tests/java_reliable.rs, Job integration-bindings): der Test prüft, dass der Queue-Enqueue-Median unter dem inline-send-Median liegt. Früher gemessen:

producer latency: queue-enqueue median = 84 ns, inline-send median = 5917 ns (70x)

Median über 20000 Iterationen je Pfad, lokal gemessen (macOS, kein Lauf auf dem Linux-Testhost) — Größenordnung deckt sich mit endpoints/gos Linux-verifizierten 20–25 ns / 4360 ns (~175–220×); der Absolutwert ist maschinen-/lastabhängig, das Verhältnis (Enqueue deutlich unter Syscall) ist der Beleg.

Status: done.


Audit-Status

6 done / 0 partial / 0 open / 0 blocked / 0 n/a (informative).

Test-Lauf: in CI, Krate-Ebene und Säulen-Jobs; die zitierten Tests mit dem letzten Ergebnis jedes Jobs in den Pipelines 8501 bis 9053 von main (python3 ci/coverage_results.py --document zerodds-endpoint-java-1.0.md):

  • python3 ci/run_integration.py integration-bindings (Job integration-bindings) — 5 Tests grün.

5 zitierte Tests grün, 0 nicht grün.

Offene Punkte: keine.