ConsistencyCheck audit and refactor — 2026-11-01¶
Scope and actual call path¶
Reviewed the complete service/examination/consistency/ConsistencyCheck.java, its calculation/result models, number-format utilities and current callers. Implemented a behavior-preserving internal refactor of this class and added characterization/concurrency tests.
The active application path found is ExaminationResource.getNextParcelLine → ExaminationService.getNextParcelLine → ConsistencyCheck.calculateNextParcelLine → the existing response mapper. No main-source caller of this class's two-argument doConsistencyCheck was found. The main figure-consistency flow uses ConsistencyHelper → GenericConsistencyCheckFactory → separate IConsistencyCheck algorithms. Those algorithms were not changed or certified by this refactor.
Findings addressed¶
| Priority | Original issue | Implemented change |
|---|---|---|
| High | A singleton Spring component stored perimeter, coordinate maps, residual maps and other request results in instance fields. Concurrent calls could overwrite another calculation's state. | Keep Messages as the only instance field, inject it through the constructor, and hold all calculations in local variables. Pass the five assessment maps through a private invocation-local record. |
| High | Both public calculation paths called shared mutable NumberUtils decimal formatters. |
Clone the existing configured formatters for each invocation. Only the copies perform formatting, retaining their existing symbols, patterns and rounding configuration. Other consumers of NumberUtils are outside scope. |
| Medium | Every X/Y residual calculation searched the entire input list for the matching start point. | Build a start-point index once, reducing expected lookup work from O(n²) to O(n). Keep case-sensitive matching and the original first-match behavior for duplicate labels. Null labels retain the old contextual-error scan path. |
| Low | Intermediate dy/dx/angle calculations were stored but never used in the returned outcome or final decision. Several comments described abandoned branches. | Remove unused intermediate calculations and obsolete comments; keep all formulas that contribute to returned values and decisions. |
| Low | A regulatory limit was assigned and then overwritten; an exception property was assigned to an outcome that was immediately discarded by rethrowing. | Remove those dead assignments while preserving the final regulatory limit and thrown exception behavior. |
| Low | Misclosure labels required multiple passes, and assessment construction used a stream with mutable exception-context side effects. | Collect misclosed side names once and build assessment rows with an explicit ordered loop. Retain list order, duplicate labels and existing output text. |
Java documents that DecimalFormat instances are generally unsynchronized and recommends separate instances for concurrent use. Java SE 25 reference
This is a structural concurrency/performance correction, not a benchmark result. No latency or production throughput claim is made.
Numerical and response behavior retained¶
- The same public method names/signatures and request/response model types remain. Only object construction changes to constructor injection.
- Angles use the existing DMS expression and four-digit format/parse rounding.
- Assessed X/Y coordinates still use the public
Math.round-basedroundAvoidat two places. Next-line coordinates still use the distinct decimal-format rounding path. Those rounding methods were deliberately not unified. - Coordinate residuals retain their four-digit formatting, lookup signs and first-duplicate semantics.
- Area retains its signed result, intermediate double/BigDecimal operations,
MathContext(15), map-key representation and two-digit formatting. No absolute-area substitution was introduced. - Closure tolerance remains
0.02 + perimeter * sqrt(sideCount) / 10000; area tolerance remains2 + perimeter² * sqrt(sideCount) / 80000. The perimeter is rounded at the same stage as before; expression order was preserved. - Existing
>and<=decisions, zero-denominator behavior, misclosed-side label order, start/end coordinate maps, area/line order fields, null/default fields and serialized numeric strings are retained for the characterized inputs. calculateNextParcelLinestill returns a new entity containing only the calculated coordinates; it does not copy source IDs or other metadata. Inputs remain unmodified.- Explicit validation/error messages and the empty-list failure type are covered by regression tests. This is not a guarantee that incidental JVM-generated null-dereference text is a stable API contract.
Logic concerns deliberately preserved¶
These findings need a separate domain decision because correcting them can change results. They were not silently folded into a behavior-preserving refactor.
High — Misclosure tests a ratio rather than residual magnitude¶
Assessed-row calculation sets dyByDx to zero when dx == 0, and getSideMisClosure tests whether the ratio is nonzero. A pure Y residual can therefore escape the line misclosure flag; a pure X residual also yields a zero ratio. Conversely, a nonzero ratio marks a line without comparing a residual distance against closure tolerance.
Recommended separate fix: establish the intended survey rule and units, then compare the approved residual magnitude/closure metric with its tolerance. Add explicit X-only, Y-only, diagonal and boundary tests. Do not assume a mathematically plausible replacement is the approved business rule. The golden vertical-only-residual case records the current behavior.
Medium — Area keys assume single-character labels¶
Area-key decoding uses fixed character offsets and single-character substrings. Multi-character point names can produce incorrect areas or failures.
Recommended separate fix: replace encoded strings with a typed point-pair representation and an explicitly ordered coordinate lookup. First decide how duplicate labels and mixed case should behave; retain a separate legacy path or migrate consumers with representative data fixtures.
Medium — Endpoint closure is not complete diagram validation¶
Validation compares the first start label with the final end label, ignoring case. It does not establish continuity of all intermediate sides, label uniqueness, minimum side count or finite coordinates/distances. Subsequent point lookup is case-sensitive.
Recommended separate fix: define supported diagrams and input validation at the application boundary, then validate all links and numeric values. Decide case normalization explicitly. Preserve error envelopes and coordinate response formats; expect acceptance/rejection behavior to change.
Medium — Locale-sensitive formatting is parsed as locale-independent numbers¶
Existing decimal symbols are preserved, including the inherited assumption that formatted output is acceptable to Double.parseDouble. Comma-decimal locales remain a concern. Double2dSerializer also formats through the default locale, separately from this class.
Recommended separate fix: define the application's numeric locale contract and standardize parsing/rounding and serialization together, with fixtures for decimal separators, negative ties and signed zero. Replacing format/parse rounding with BigDecimal.setScale can change binary-tie behavior and needs parity tests.
Verification¶
Before changing production code, captured two golden files from the original implementation:
- 12 full figure outcomes, each recording raw values and serialized JSON. Cases include square/triangle geometry, both orientations, incorrect area, fractional negative coordinates, duplicate start labels, DMS inputs, zero distance, pure-Y residual and area-tolerance boundaries.
- Six next-line results, covering cardinal directions, fractional DMS, negative coordinates/distances and negative rounding ties.
ConsistencyCheckTest now compares against those immutable captured expectations. It does not regenerate expected values during test execution.
The class has 17 passing tests, including raw/serialized parity, unchanged inputs, explicit failures, public-rounding behavior, 96 concurrent full calculations and 96 concurrent next-line calculations on shared instances. Eight workers synchronize their start to exercise overlapping requests. No Oracle/Redis services are involved.
The combined run also includes all six mapper migration checks: 23 tests passed, zero failures/errors/skips. Main and test compilation completed as part of that run, with existing unrelated deprecation notes. This was not a complete repository test suite, HTTP endpoint test, live-data survey verification or review of the other consistency algorithms.