Preserve Java 8 buffer descriptors in persisted Map I/O

[peter-lawrey]

A Chronicle Map artifact compiled on a modern JDK with Java 8 source/target settings can link header cursor operations to Java 9+ covariant ByteBuffer methods. On Java 8, creating a persisted Map then fails with NoSuchMethodError.

Use Buffer-typed cursor calls in ChronicleMapBuilder and the global-state read in VanillaChronicleHash.initBeforeMapping(). Add a persistence regression that writes entries, reopens the Map, recovers it with exclusive access, and reopens it again while checking retained values and temporary-file deletion.

This extracts the production compatibility work identified in #588. Actual Java 8 execution showed the builder-only changes were incomplete: creation succeeded, but reopening failed at the additional ByteBuffer.flip() call. The extra cast fixes that same persistence path. Three files change; the POM and JUnit framework are unchanged.

Validation:

Java-21-built artifact, executed on Java 8u502	Result
Current develop baseline	Fails creating the Map: ByteBuffer.position(int):ByteBuffer in writeHeader()
Builder-only extraction	Creation succeeds; reopening fails: ByteBuffer.flip():ByteBuffer in initBeforeMapping()
Final patch	Create, reopen, recover and reopen-after-recovery pass; key/value assertions and file cleanup pass

The runtime check verified that ChronicleMapBuilder was loaded from the requested packaged JAR. It did not use target/classes or rebuild Map on Java 8. Disassembly confirms Buffer-returning cursor descriptors at all changed call sites.

Full mvn verify -Dsurefire.rerunFailingTestsCount=0 on Java 21 passed: 1,317 tests, 82 existing skips. The baseline had 1,316 tests and the same skip count. The binary compatibility enforcer also passed.

Reproduce the packaged-artifact check

With JAVA_HOME and PATH pointing to JDK 21 for Maven:

mvn clean verify -Dsurefire.rerunFailingTestsCount=0 -l verify-java21.log
mvn dependency:build-classpath -Dmdep.outputFile=target/test-classpath.txt
map_test_deps=$(cat target/test-classpath.txt)
/path/to/jdk8/bin/java -ea \
  -cp "target/test-classes:target/chronicle-map-2026.2-SNAPSHOT.jar:$map_test_deps" \
  org.junit.runner.JUnitCore net.openhft.chronicle.map.PersistedMapHeaderTest

Validated final JAR SHA-256: ef49507dd461f8147ec512230b7cdeb56e6adadc045ab10c589eac83a723a739.

Validation environment and dependency receipt

Linux x86_64; Maven 3.9.11; OpenJDK 21.0.12 and 8u502. Surefire 3.1.2, JUnit 4.13.2, Vintage 5.10.0. Failing-test reruns explicitly disabled with -Dsurefire.rerunFailingTestsCount=0. Builds start from develop at 0c25269da8d12e3e1cd10c7f4c74ae35a017ab2c.

Resolved Chronicle dependencies: Core 2026.6; Bytes 2026.4; Wire 2026.10-SNAPSHOT; Values 2026.2; Threads 2026.3; Algorithms 2026.2; Affinity 2026.2; Posix 2026.2; Test Framework 2026.2; JLBH 2026.2. Parent and third-party BOM: 2026.0. XStream: 1.4.21.

Mutable-input SHA-256:

chronicle-bom-2026.0-SNAPSHOT.pom  5e9ce529e8aaa9f9930658b2ef59222ebffe164fb8e6d31ce0b4e204cb1d55a0
chronicle-wire-2026.10-SNAPSHOT.jar  77afd5d4236c738c25980c268858879b6c929e70486b829b5e4a434dd6b31c87

The unchanged baseline also passed full mvn verify: 1,316 tests, 82 existing skips. Windows/macOS and downstream projects were not run locally.

[Copilot]

🟢 Approval recommended

The compatibility fix is focused, regression-tested, and has no unresolved issues.

Pull request overview

Preserves Java 8 compatibility for persisted Chronicle Maps built on modern JDKs.

Changes:

• Uses Java 8-compatible Buffer cursor descriptors.
• Adds persistence lifecycle and recovery regression coverage.

File summaries

File	Description
src/test/java/net/openhft/chronicle/map/PersistedMapHeaderTest.java	Tests creation, reopening, recovery, data retention, and cleanup.
src/main/java/net/openhft/chronicle/map/ChronicleMapBuilder.java	Uses compatible persisted-header cursor operations.
src/main/java/net/openhft/chronicle/hash/impl/VanillaChronicleHash.java	Fixes buffer flipping when reopening persisted maps.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.