Skip to content

decision-log.adoc

Latest commit

 

History

History
94 lines (85 loc) · 6.45 KB

decision-log.adoc

File metadata and controls

94 lines (85 loc) · 6.45 KB
Raw

Chronicle Values - Decision Log

Table of Contents

This file captures component-specific architectural and operational decisions for the Chronicle Values module. Identifiers follow the <Scope>-<Tag>-NNN pattern; numbers are unique within the VAL scope and link back to CV-* requirements where relevant.

VAL-FN-101 Value Interfaces as Single Source of Truth

Date

2025-11-14

Context

  • Chronicle Values generates constant-size flyweight accessors and on-heap bean implementations from user-defined value interfaces.

  • Without a single, normative definition of fields and behaviours, schemas can drift between documentation, heap models and off-heap layouts.

  • Requirements: CV-FN-001, CV-FN-003, CV-FN-004, CV-FN-007, CV-DOC-022.

Decision

  • Treat value interfaces as the single source of truth for data layout and semantics; generated native and heap implementations must be derivable from the interface specification alone.

  • Keep net.openhft.chronicle.values.internal classes as implementation detail; consumers interact with generated types via public APIs and helper factories (Values.newNativeReference, Values.newHeapInstance).

Alternatives
* Hand-written POJOs and manual serializers alongside value interfaces

  • Pros: Maximum flexibility for special cases.

  • Cons: Duplication of schema knowledge; high risk of divergence between representations.

* External schema descriptions (IDLs, separate metadata files) driving generation

  • Pros: Potential multi-language support.

  • Cons: Additional toolchain complexity; weak alignment with Chronicle Values API design centred on Java interfaces.

Rationale

  • A single specification point keeps the mental model simple and reduces the chance of layout and behaviour drift.

  • Aligns the library with its documented usage in project-requirements.adoc and README, where value interfaces already express structure, annotations and supported method patterns.

Impact

  • Documentation and examples must emphasise value interfaces as the canonical schema.

  • Tests for new features should target the interface level, exercising both native and heap implementations derived from the same definition.

Links

VAL-NFP-111 Constant-Size Flyweights Backed by Chronicle Bytes

Date

2025-11-14

Context

  • Chronicle Values advertises generation of constantly-sized flyweight accessors backed by Chronicle Bytes stores.

  • Performance requirements call for predictable memory layout, low allocation rates and efficient off-heap access.

  • Requirements: CV-NFP-011, CV-NFP-012, CV-NFP-013, CV-NFP-015.

Decision

  • Maintain a constant-size layout for each value interface, using annotations such as @MaxUtf8Length, @Array, @Range and @Align to bound variable-length fields and control packing.

  • Continue to back native implementations with BytesStore and expose Byteable so callers can attach flyweights to existing Bytes regions without extra allocation.

Alternatives
* Variable-size layouts that grow with actual field content

  • Pros: Denser packing for sparse or rarely populated fields.

  • Cons: Unpredictable offsets, slower random access and more complex schema evolution.

* Heap-only representations with on-demand serialisation to Bytes

  • Pros: Familiar object model and tooling.

  • Cons: Higher GC pressure and extra copy cost on each serialisation boundary.

Rationale

  • Fixed layouts align with Chronicle’s low-latency and off-heap design goals, keeping field offsets stable and enabling efficient CAS and alignment-sensitive operations.

  • Annotation-driven configuration keeps the model expressive while preserving the constant-size property.

Impact

  • Interface authors must supply appropriate annotations for strings, arrays and constrained numeric fields to avoid accidental layout bloat.

  • Changes to annotations or method signatures can be breaking at the binary layout level and must be reviewed against persistence and IPC use cases.

Links

VAL-SPOT-301 Code-Review Profile Suppressions for Legacy Generators

Date

2025-10-28

Context

  • Enabling the shared code-review Maven profile surfaced long-standing SpotBugs findings (EI_EXPOSE_REP*, SIC_INNER_SHOULD_BE_STATIC_ANON, DP_CREATE_CLASSLOADER_INSIDE_DO_PRIVILEGED, IMPROPER_UNICODE, NM_SAME_SIMPLE_NAME_AS_SUPERCLASS, CT_CONSTRUCTOR_THROW, URLCONNECTION_SSRF_FD).

  • Several warnings stem from the generator pipeline intentionally sharing reflective metadata, anonymous inner classes, and bridge class loader bootstrapping that cannot be reworked safely during profile onboarding.

  • Test coverage remains below the default 80/70 percent thresholds because the module relies heavily on generated code and integration tests.

Decision Statement

  • Suppress the legacy SpotBugs findings via src/main/config/spotbugs-exclude.xml with tags VAL-SPOT-301 to VAL-SPOT-310, and annotate the affected code with rationale where practicable.

  • Override JaCoCo thresholds inside the module’s code-review profile (tag VAL-TEST-401) to 0.0 pending dedicated test creation.

Alternatives Considered
* Immediate generator refactor to remove reflective exposure and anonymous classes

  • Pros: Eliminates suppressions permanently.

  • Cons: High-risk change touching ABI and generated sources; would stall profile adoption.

* Failing the build until coverage targets are achieved

  • Pros: Forces investment in tests now.

  • Cons: Blocks migration work; tests require broader design changes outside the current scope.

Rationale for Decision

  • Documented suppressions unblock the profile while signalling the debt through tagged comments and this record.

  • Deferring coverage thresholds within the profile isolates the deviation and keeps stricter defaults available for other modules.

Impact & Consequences

  • TODO.adoc records follow-up tasks tied to the suppression tags and coverage gap.

  • Future generator and testing work must revisit the tagged areas to retire the suppressions and restore standard coverage goals.