v1.3.0

Fletch 1.3.0

This version adds configurable extraction limits, reusable mapping sessions and
experimental build-time lookup generation. It also tightens validation of visited
XML content and reduces canonical-cache memory for small sets of values.

Changes

• XmlLimits supplies immutable per-extraction budgets for original input bytes,
  element depth/count, UTF-8 name length, attribute count and selected content.
  Cursor and mapping APIs accept the same configuration and retain their existing
  two-argument entry points.
• XmlMapping.openSession() reuses one dedicated engine on its creating thread.
  Sessions reject cross-thread access and reentrant extraction, recover after
  parsing/callback failures, and release the engine on close.
• The optional generator specializes element/attribute lookup from the existing
  DSL. It checks mapping fingerprints and complete name bytes while retaining the
  shared parser, callbacks and resource contracts. Codegen is experimental and
  built from source; generated applications need only the core and java.base.
• End-tag checks compare full names, including bytes beyond the hash prefix.
  Selected text, CDATA and attributes reject invalid UTF-8/XML characters. Scanned
  start tags validate attribute syntax and duplicate raw names.
• Extraction releases caller-owned sources and drafts after success or failure,
  including preparation failures, and trims unusually large scratch buffers.
• Canonical caches start at 16 slots and grow to at most 1,024, preserving cached
  identities and full byte comparisons. Benchmark tools cover rotating corpora,
  attribute validation, concurrent workers and paired measurements.

Upgrading from 1.2.0

Java 17 remains the minimum. Existing public signatures/descriptors remain
available, and the runtime adds no external dependency. Valid applications still
need to check their document sizes and validation expectations:

1. Previously accepted malformed input can now throw XmlException. Check
   producers for mismatched end tags, invalid selected characters and malformed
   or duplicate attributes; a shared 16-byte name prefix is no longer sufficient
   for end-tag equality.
2. Every scanned start tag is limited to 1,024 attributes. Selected text and
   scanned attributes have a 16 MiB UTF-8 content ceiling before entity decoding
   and trimming. Text/CDATA runs inside a selected value share its budget. These
   ceilings can be lowered with XmlLimits, but cannot be raised.
3. Default limits add no input-byte, depth, element-count or name-length budget.
   Choose explicit budgets for the application's document contract when needed.
   Arrays and strings are checked in full; mapping streams are limited as read,
   including read-ahead, and may leave trailing content unchecked on early exit.
4. Extraction remains selective. strictSkip() verifies end tags in ignored
   subtrees; it does not certify whole-document XML well-formedness or validate
   namespaces/XSD. Use a separate validation step when that is required.
5. Input streams stay owned by the caller. Earlier callback side effects are not
   rolled back after a later failure. Parse/resource/I/O failures use
   XmlException; conversion failures retain their Java exception types.
6. Create, use and close a session on the same worker thread, preferably once for
   a batch. Xml.extract() already pools engines. Sessions and codegen are
   optional choices, and neither promises a throughput improvement for every
   workload. Regenerate code when upgrading the matching core/generator versions.

The resource contract, session guide
and codegen guide describe the API and ownership details.

Performance evidence

On the measured HotSpot layouts, the canonical-cache graph for two state codes
fell from 16,576 to 448 bytes; for all 27 codes, from 18,376 to 3,016 bytes.
Growing to the maximum still adds 16,416 temporary array bytes. This measures
the cache graph, not the whole application's memory footprint.

Warmed throughput estimates did not establish an absence of regression: the
complete-collision case was -3.00%, with a descriptive 95% interval of
[-10.64%, +5.30%]. A separate session-lifecycle comparison reduced allocation in
all six fixtures, but batch sessions took 7.32% longer for complete collisions
than a fresh session per XML; NF-e timing was inconclusive. That study does not
compare with the pooled API, and 18/48 forks showed drift above +/-5%.

See the recorded results and limitations.
These local studies do not represent a production document distribution.

What's Changed

• Harden XML extraction and add limits, sessions and optional codegen by @robsonkades in #6
• Prepare 1.3.0 release and synchronize codegen versions by @robsonkades in #7

Full Changelog: v1.2.0...v1.3.0

v1.2.0

What's Changed

• replace StAX/Woodstox parser with native byte-scanning engine by @robsonkades in #4
• replace StAX with a byte-level engine, order-tolerant cursor and declarative mapping by @robsonkades in #5

Full Changelog: v1.1.0...v1.2.0

v1.1.0

What's Changed

• feat: read child elements regardless of document order by @robsonkades in #3

Full Changelog: v1.0.0...v1.1.0

v1.0.0

What's Changed

• initial version by @robsonkades in #1
• add benchmarks assembly by @robsonkades in #2

New Contributors

• @robsonkades made their first contribution in #1

Full Changelog: https://github.com/robsonkades/fletch/commits/v1.0.0