Follow-up to the discussion in #3110. @imbajin confirmed the testing and validation groundwork can start before any Rust decision, so this issue tracks the Java-only part: a selection matrix for the first PoC candidate and golden compatibility fixtures for the codec classes.
Scope
Three deliverables, all plain Java against the current build:
- A selection matrix for PoC candidates (first cut below, to be refined in this thread).
- A golden fixture corpus for
LongEncoding plus a replay test that runs it against the current implementation.
- Short written notes on the behavioral contract the fixtures lock down (edge cases, error behavior, invariants).
Non-goals
No Rust, no JNI, no Cargo, no packaging changes, no new Maven modules, no runtime wiring. Those wait for the component decision, a mentor, and a design review with contributors who have deeper Rust experience, as discussed in #3110.
Selection matrix
Criteria: an existing test oracle, enough call sites to matter, work per call big enough to survive a JNI crossing, and, following the maintainer feedback in #3110, keeping the Java implementation alive has to stay cheap, since graceful fallback is a requirement.
| Candidate |
Oracle |
Fallback cost |
Notes |
LongEncoding |
LongEncodingTest (684 lines) |
low, pure functions |
output feeds storage keys, so the contract needs locking either way |
NumericUtil |
NumericUtilTest (475 lines) |
low |
coupled to LongEncoding.encodeNumber, candidate for the same corpus later |
BytesBuffer |
BytesBufferTest (1351 lines) |
high |
persisted format, 30+ callers, a fallback would have to stay byte-identical |
IntSet / IntMap |
IntSetTest, IntMapTest |
high |
concurrent structures on Unsafe, a live double implementation risks divergence |
With the fallback criterion the concurrent structures and the serializer drop out of round one. LongEncoding is the first fixture target. That is a choice about where to write fixtures first, not a decision that it becomes the Rust PoC.
Fixture shape
Plain ASCII, line-based (TSV with \uXXXX escapes for non-ASCII), checked into test resources so it needs no extra dependency to read. It covers: round trips across the full value range including Long.MIN_VALUE/MAX_VALUE (the encoding does intentional wrapping arithmetic), arbitrary UTF-16 input on the decode side (valid inputs are ASCII, invalid ones are not), the error cases (IllegalArgumentException vs NumberFormatException vs NPE on null), and the length limits.
The replay test is JUnit 4 and compiles at the Java 8 level, since that is the current hugegraph-commons baseline. Root is Java 11. Java 17 / commons Java 11 from #3117 are treated as declared targets, not assumptions.
Acceptance
Follow-up to the discussion in #3110. @imbajin confirmed the testing and validation groundwork can start before any Rust decision, so this issue tracks the Java-only part: a selection matrix for the first PoC candidate and golden compatibility fixtures for the codec classes.
Scope
Three deliverables, all plain Java against the current build:
LongEncodingplus a replay test that runs it against the current implementation.Non-goals
No Rust, no JNI, no Cargo, no packaging changes, no new Maven modules, no runtime wiring. Those wait for the component decision, a mentor, and a design review with contributors who have deeper Rust experience, as discussed in #3110.
Selection matrix
Criteria: an existing test oracle, enough call sites to matter, work per call big enough to survive a JNI crossing, and, following the maintainer feedback in #3110, keeping the Java implementation alive has to stay cheap, since graceful fallback is a requirement.
LongEncodingLongEncodingTest(684 lines)NumericUtilNumericUtilTest(475 lines)LongEncoding.encodeNumber, candidate for the same corpus laterBytesBufferBytesBufferTest(1351 lines)IntSet/IntMapIntSetTest,IntMapTestUnsafe, a live double implementation risks divergenceWith the fallback criterion the concurrent structures and the serializer drop out of round one.
LongEncodingis the first fixture target. That is a choice about where to write fixtures first, not a decision that it becomes the Rust PoC.Fixture shape
Plain ASCII, line-based (TSV with
\uXXXXescapes for non-ASCII), checked into test resources so it needs no extra dependency to read. It covers: round trips across the full value range includingLong.MIN_VALUE/MAX_VALUE(the encoding does intentional wrapping arithmetic), arbitrary UTF-16 input on the decode side (valid inputs are ASCII, invalid ones are not), the error cases (IllegalArgumentExceptionvsNumberFormatExceptionvs NPE on null), and the length limits.The replay test is JUnit 4 and compiles at the Java 8 level, since that is the current
hugegraph-commonsbaseline. Root is Java 11. Java 17 / commons Java 11 from #3117 are treated as declared targets, not assumptions.Acceptance