Package dev.omnist.codec

Class XmlCodec

java.lang.Object

dev.omnist.codec.XmlCodec

public final class XmlCodec
extends Object

Codec for reading and writing the Omnist Document model as XML (omnist-spec §7.3), built on javax.xml.parsers/DOM.

Reading: always parses namespace-aware; a document's single root element becomes the sole top-level edge; child elements become nested edges, preserving repeated-element order (this is the one codec where cross-label interleaving both reads and writes faithfully — every other codec's writer groups same-label edges). Attribute and namespace-prefix information is discarded on read, silently per omnist-spec §9.4 D-3 (no diagnostic is emitted for this — it's a spec-mandated lossy conversion, not an oversight).

Writing: scalar leaves are stringified per XML's own type rules (XML_INT_RE/XML_NUM_RE); a leaf label that isn't a legal XML name is sanitized, falling back to an underscore-prefixed form.

This class is stateless; all methods are static.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MAX_INPUT_LENGTH	Maximum accepted input length in characters, guarding against oversized XML input.

Method Summary

Modifier and Type	Method	Description
static WriteReport	check(Document node)	Computes what adjustments write(Document) would make to node without actually producing XML text.
static Document	read(String text)	Parses XML text into a Document without schema guidance.
static Document	read(String text, Schema schema)	Parses XML text into a Document, optionally with schema guidance.
static String	write(Document node)	Serializes a Document to XML text, non-strict (dropping/sanitizing unrepresentable content rather than throwing).
static String	write(Document node, boolean strict, WriteReport report)	Serializes a Document to XML text.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_INPUT_LENGTH

public static final int MAX_INPUT_LENGTH

Maximum accepted input length in characters, guarding against oversized XML input.

See Also:

• Constant Field Values

Method Details

read

public static Document read(String text)

Parses XML text into a Document without schema guidance. Equivalent to read(text, null).

Parameters:

text - the XML text; must not be null

Returns:

the parsed document

Throws:

RuntimeException - if the XML is not well-formed or exceeds MAX_INPUT_LENGTH

read

public static Document read(String text,
 Schema schema)

Parses XML text into a Document, optionally with schema guidance.

Unlike the other three format codecs (whose read(text, schema) overload ignores schema entirely, or in JsonCodec's case accepts it without acting on it — schema-driven coercion there happens in a later Materializer stage instead), XML text is inherently ambiguous about scalar kind: every attribute and element value is just a string until something says otherwise. When schema is non-null, its root record's field types are used to pre-resolve strings that look like booleans/integers/numbers into the matching Java type before the document is built, so a later validate/materialize call sees a typed value rather than a string it would otherwise have to coerce blind.

Parameters:

text - the XML text; must not be null

schema - if non-null, guides scalar-kind resolution for ambiguous string content as described above; if null, every scalar is read as a plain string

Returns:

the parsed document

Throws:

RuntimeException - if the XML is not well-formed or exceeds MAX_INPUT_LENGTH

write

public static String write(Document node)

Serializes a Document to XML text, non-strict (dropping/sanitizing unrepresentable content rather than throwing). Equivalent to write(node, false, null).

Parameters:

node - the document to serialize; must have exactly one top-level edge (XML requires a single root element)

Returns:

the XML text

Throws:

WriteException - if node does not have exactly one top-level edge

write

public static String write(Document node,
 boolean strict,
 WriteReport report)

Serializes a Document to XML text.

Parameters:

node - the document to serialize; must have exactly one top-level edge (XML requires a single root element)

strict - if true, throws when the document contains any adjustment (e.g. a sanitized element name); if false, applies the adjustment and continues

report - if non-null, every adjustment made during writing is appended here

Returns:

the XML text

Throws:

WriteException - if node does not have exactly one top-level edge, or if strict is true and an adjustment was required

check

public static WriteReport check(Document node)

Computes what adjustments write(Document) would make to node without actually producing XML text.

Parameters:

node - the document to check

Returns:

the adjustments (e.g. sanitized names, dropped nulls) that a write of node would require