Document Chronicle Map architecture & system properties; tidy APIs, quality rules, and tests

[peter-lawrey]

This PR is primarily documentation, quality, and test clean-up work for Chronicle Map, with only very minor behavioural changes. It introduces explicit architectural/requirements docs, documents key system properties, relaxes some Checkstyle rules for legacy tests, and upgrades the BOM.

---

Functional changes

These are the changes that could affect runtime behaviour or public APIs.

1. JSON import/export now uses NIO streams

   • JsonSerializer.createInputStream(...) and createOutputStream(...) now use Files.newInputStream(...) / Files.newOutputStream(...) instead of FileInputStream / FileOutputStream.
   • Behaviour is intended to be equivalent, but this routes I/O through the NIO APIs and may interact slightly differently with file handles and filesystems, especially on platforms with strict I/O policies.

2. Constructor / API exception signatures simplified

   • ReplicatedChronicleMap(ChronicleMapBuilder<K,V>) no longer declares throws IOException; the implementation did not actually throw checked I/O in normal construction. Callers no longer need to handle IOException at construction time.
   • FindByName.from(String) now only declares IllegalArgumentException, removing IOException, TimeoutException, and InterruptedException from the signature. Implementations and call-sites in this module were already not relying on those checked exceptions.

3. Small behavioural tweaks in test/demo utilities

   • Several long-running or busy-wait loops in test/demo code (for example CHMLatencyTestMain and the “dirty read” lock examples) now use Thread.yield() or similar instead of pure empty spin loops. This reduces CPU burn in those harnesses but does not affect the core Chronicle Map runtime behaviour.
   • A few test harnesses now use JUnit’s assertEquals / assertNull / assertSame etc. in ways that more precisely assert the intended behaviour (for example, ChronicleMapEqualsTest, MapCloseTest).

No intentional changes were made to the Chronicle Map data structures, locking algorithms, on-disk format, or replication semantics.

---

Non-functional changes

Documentation & AsciiDoc structure

• Project-wide AsciiDoc attributes

  • Added :lang: en-GB and :source-highlighter: rouge to:

    • ReadMe.adoc
    • benchmark/README.adoc
    • Multiple user-facing docs under docs/CM_*.adoc
    • New and existing documents under src/main/docs/*.adoc

  • Aligns docs with Chronicle’s house style and consistent syntax highlighting.

• Typo and wording fixes

  • benchmark/README.adoc: “Corsair MP600 driver” → “Corsair MP600 drive”.
  • A few headings and examples in CM docs clarified (e.g. ==== 1. Data rate → ==== Data rate).

• New system properties reference

  • New docs/systemProperties.adoc describing Chronicle Map system properties, including:

    • chronicle.map.creation.debug
    • chronicle.map.file.lock.timeout.secs
    • chronicle.map.sparseFile
    • chronicle.map.disable.locking
    • net.openhft.chronicle.map.lockTimeoutSeconds

  • Captures default values, behaviour, and associated internal variables (e.g. MAP_CREATION_DEBUG, FILE_LOCK_TIMEOUT).

• New architecture and compliance documents

  Added a Chronicle Map documentation spine under src/main/docs/:

  • architecture-overview.adoc

    • High-level context for Chronicle Map within the Chronicle stack.
    • Outlines dependencies (Bytes, Core, Threads, Wire) and the off-heap segmented hash design backed by memory-mapped files.

  • decision-log.adoc

    • Component-specific ADRs using the <Scope>-<Tag>-NNN pattern with MAP-* identifiers, e.g.:

      • MAP-FN-101 Off-heap Segmented Hash Map Design
      • MAP-NF-O-201 Sizing and Capacity Configuration Via Builder

  • project-requirements.adoc

    • Initial MAP-* requirements catalogue:

      • Functional: MAP-FN-001–003 for core map operations, persistence, and builder usage.
      • Non-functional: performance (MAP-NF-P-*), operability (MAP-NF-O-*), and security (MAP-NF-S-*) skeletons.
      • Traceability table linking requirements to representative tests (e.g. EntryCountMapTest, BasicReplicationTest, HugeSparseMapTest).

  • testing-strategy.adoc

    • Describes test layers (unit/integration/perf), referencing key tests and how they cover MAP-* requirements.
    • Clarifies expectations around latency tests (CHMLatencyTestMain, PageLatencyMain) versus regular CI runs.

Build, quality and tooling

• BOM upgrade

  • Root pom.xml:

    • net.openhft:third-party-bom upgraded from 3.27ea5 to 3.27ea7.

  • This may pull in newer third-party dependency versions (logging, XStream, etc.); runtime behaviour is expected to stay compatible but this change should be watched in CI and downstream builds.

• Javadoc plugin cleanup

  • Removed -Xdoclint:none from the maven-javadoc-plugin configuration.
  • Javadoc builds now rely on the existing code/doc quality rather than globally disabling doclint; this may surface previously hidden documentation issues during site/build steps.

• Checkstyle suppressions for legacy test/example code

  • checkstyle-suppressions.xml expanded to suppress CommentsIndentation and/or VariableDeclarationUsageDistance for a number of older tests and examples (e.g. DirtyRead*, CHMUseCasesTest, LargeEntriesTest, MarshallableReaderWriterTest, etc.).
  • Keeps the main codebase and new tests under strict style rules while acknowledging legacy layout in demo/test files.

Code quality and refactoring (no intended behaviour change)

• Core implementation clean-ups

  • Marked several fields as final where they are never reassigned (e.g. iterator fields, startTime, test constants).

  • Removed unused imports and unused fields (e.g. ByteBufferDataAccess, WrappedValueBytesData.cachedWrappedValueRead).

  • Tidied lengthy generated classes (CompiledMapIterationContext, CompiledMapQueryContext, CompiledReplicated*) by:

    • Normalising spacing and switch style.
    • Simplifying generic casts (((T) ...)) and returns.
    • Adding small clarifying comments where code mirrors reference algorithms.

  • These changes are purely structural/readability improvements; logic paths and state transitions are preserved.

• Safer / clearer I/O usage

  • FileLockUtilTest and ChronicleMapImportExportTest now use Files.newInputStream/newOutputStream and localise some variables, improving clarity and resource handling in tests.

• Test suite modernisation

  • Many tests:

    • Drop unnecessary checked exceptions from method signatures (throws IOException, InterruptedException, ...) where not needed.
    • Use more precise JUnit assertions (assertNull, assertSame, assertNotEquals, assertArrayEquals).
    • Introduce small helper methods and constants (e.g. ENTRIES, ENTRY_SIZE constants in large-entry tests).
    • Replace bare fail() with JUnit 5 Assertions.fail() where appropriate.

  • ParallelStartupTest now uses JUnit 5 @RepeatedTest and Assertions.assertEquals for clarity.

  • Numerous examples/tests have minor readability improvements (renamed methods like _test() → runTest() / runPerformanceIteration(), simplified interfaces, removed redundant public modifiers).

• Utility and example tweaks

  • ProcessInstanceLimiter:

    • Uses FileSystems.getDefault().getSeparator() instead of System.getProperty("file.separator") for the default map path.
    • Slightly refactors the max-processes CAS logic to be more compact while keeping behaviour identical.

  • Many example interfaces (PortfolioAssetInterface, DemoOrderVOInterface, MyFloats, etc.) simplified by removing redundant public qualifiers and using final fields where appropriate.

---

Notes / risks

• The only potentially user-visible behaviour change is the switch to NIO file streams in JsonSerializer, but this is expected to be transparent.
• The BOM bump to 3.27ea7 may affect transitive dependency versions; downstream users should watch their dependency trees and runtime logs for subtle changes.
• All other changes should be behaviour-neutral and focused on documentation, maintainability, and tooling.

[sonarqubecloud]

Quality Gate failed

Failed conditions
21.43% Condition Coverage on New Code (required ≥ 35%)

See analysis details on SonarQube Cloud