CAMEL-24406: camel-xml-jaxp: add prolog guard to XmlConverter.toDOMDocument to avoid SAXParseException for non-XML content

[mayurbm]

Summary

Fixes CAMEL-24406.

XmlConverter.toDOMDocument(byte[], Exchange) and toDOMDocument(StreamCache, Exchange) passed content directly to DocumentBuilder.parse() without checking whether it could plausibly be XML. Non-XML content (empty body, JSON error response, plain-text HTTP response, BOM-only) triggered a SAXParseException deep inside the JDK parser with expensive DOM allocation first.

JIRA

CAMEL-24406

Fix

Add a cheap static looksLikeXml(byte[]) helper (handles UTF-8/UTF-16 BOMs and leading whitespace) and guard the two toDOMDocument overloads. When content cannot be XML, throw TypeConversionException immediately — before DocumentBuilder.parse() is called — so:

• No DOM allocation occurs
• The Camel error handler fires with a clear, diagnosable message
• The exchange fails explicitly (not silently with a null body)

Changes

• XmlConverter.java — toDOMDocument(byte[], Exchange) and toDOMDocument(StreamCache, Exchange): add looksLikeXml guard, throw TypeConversionException for non-XML; add looksLikeXml(byte[]) static helper
• XmlConverterPrologTest.java (new) — 16 tests: 13 unit tests for looksLikeXml + 3 integration tests asserting TypeConversionException is thrown for empty, JSON, plain-text payloads

Test Results

AI Attribution

This contribution was developed with AI assistance using Claude Code.

[mayurbm]

Priority Justification

This is not just a cosmetic exception-message improvement. The impact under real production load is significantly worse than it appears:

Why this deserves high priority

1. Expensive DOM construction before failure

Invalid / non-XML content does not just produce a clean exception — it forces expensive DOM construction first. The JDK XML parser allocates internal buffers, parser state, and partial DOM nodes before it reaches the prolog and throws. Every failed conversion has already consumed heap memory proportional to the payload size.

2. Retries multiply the cost

Retries multiply the cost because the same stream objects are rebuilt on every attempt. A single bad payload hitting a retry-enabled route or a CXF fault path can trigger 3–5 full parse attempts, each allocating and immediately abandoning the same DOM scaffolding.

3. Heap and GC pressure under load

Under load or with large bad payloads this becomes a significant heap-memory and GC problem, even though the final outcome is always a parse failure. In high-throughput CXF/SOAP services receiving occasional non-XML error responses (upstream 5xx HTML pages, JSON fault bodies), this pattern can saturate the old-gen heap and trigger full GC pauses or OutOfMemoryError — all for payloads that were never going to parse successfully. in our one production landscape 5 million such errors seen with different tenants.

---

Mitigation (until this fix is merged)

Perform a cheap prefix + size check on the raw / before any type conversion or CXF binding runs. This rejects the payload early and avoids the DOM allocation entirely:

The fix in this PR moves exactly this check into itself, making it automatic for all routes without requiring any application-level workaround.

[mayurbm]

Update: switched from return null to throw TypeConversionException

The initial implementation used @Converter(allowNull = true) and returned null for non-XML content. This was incorrect — returning null lets the exchange continue with a null body, causing a silent NullPointerException or data loss downstream instead of a clean, diagnosable failure.

Updated approach: throw TypeConversionException immediately when the prolog check fails. This:

• Fires the Camel error handler with a clear message
• Avoids DOM allocation entirely (check runs before DocumentBuilder.parse() is called)
• Produces a directly actionable log entry:

Error during type conversion from type: byte[] to the required type: org.w3c.dom.Document
Payload does not start with a valid XML prolog
(possible causes: empty body, JSON/HTML error response, wrong encoding)

Local validation after update:

• mvn formatter:format impsort:sort — no changes needed
• Tests run: 16, Failures: 0, Errors: 0, Skipped: 0 [JDK 21 / Maven 3.9]
  • 13 unit tests for looksLikeXml()
  • 3 integration tests asserting TypeConversionException is thrown for empty, JSON, plain-text payloads