XOM XML Library: Strict Correctness by Design

The XOM (XML Object Model) library is an open-source, tree-based Java API designed by Elliotte Rusty Harold to provide simple, robust, and safe XML processing. Unlike traditional APIs such as the standard W3C Document Object Model (DOM), which often allow developers to construct illegal XML representations in memory, XOM guarantees that an invalid XML document can never be created through its API. This article explains what XOM is, how it differs from traditional XML models, and the architectural principles it employs to enforce strict XML correctness and structural invariants by design.

What Is XOM?

XOM is a lightweight, high-performance Java library for parsing, building, and manipulating XML. While it shares conceptual similarities with DOM and JDOM—representing XML documents as hierarchical, in-memory tree structures—its primary differentiator is an uncompromising focus on correctness and predictability.

In standard DOM implementations, memory structures can easily drift into states that violate the XML 1.0 specification, such as elements containing illegal characters or unmapped namespace prefixes. These errors are often only discovered downstream during serialization. XOM eliminates this category of bugs by rejecting invalid data the moment it is introduced.

Structural Invariants Enforced by Design

XOM enforces strict structural rules throughout the lifecycle of an XML node. These invariants prevent the internal tree model from ever entering an inconsistent state:

• Strict Single-Parent Rule: In XOM, a node (such as an Element, Text, or Comment) can have at most one parent. If you attempt to add an already attached node to another element without detaching it first, XOM immediately throws an IllegalAddException. This prevents circular references and multi-parent graphs.
• Document Hierarchy Constraints: A Document object in XOM strictly enforces root-level rules: it must contain exactly one root Element, and it cannot contain raw Text nodes as direct children.
• No Orphaned Attribute Nodes: In XOM, attributes are not generic nodes in the tree hierarchy. They belong strictly to their parent Element, preventing disconnected or misapplied attribute objects.

Namespace and Naming Correctness

Namespace handling is one of the most common sources of subtle bugs in XML processing. XOM enforces strict namespace and naming invariants on creation and modification:

• Instant Validation of Names: Element and attribute names are validated at the moment of instantiation. If a name violates XML Name or NCName production rules (such as starting with a number or containing illegal punctuation), an IllegalNameException is thrown immediately.
• Namespace Consistency: Whenever an element or attribute is assigned a prefix, XOM requires a corresponding namespace URI. It prevents prefix collisions, undeclared prefixes, or the use of reserved prefixes like xml or xmlns in illegal contexts.
• No Unchecked Mutability: Modifying a prefix or namespace URI causes XOM to verify the change against the surrounding context to ensure no prefix shadowing or namespace conflicts are introduced.

Character Data and Content Integrity

XOM actively validates character data to prevent the insertion of characters that are illegal under the XML 1.0 specification:

• Illegal Character Rejection: Characters such as null bytes (\u0000) or specific low-order control characters (outside of allowed whitespaces like carriage returns, newlines, and tabs) cannot be inserted into Text nodes, attribute values, or comments.
• Automatic Entity Encoding: When serialized, XOM automatically escapes reserved characters like <, >, and &, ensuring that the resulting string or stream is guaranteed to be well-formed XML.

The Fail-Fast Philosophy

The core design pattern of XOM is fail-fast validation via unchecked exceptions. Instead of relying on boolean return values or delayed validation during serialization, XOM constructors and mutation methods immediately throw specific runtime exceptions (subclasses of XMLException, such as IllegalDataException or NoSuchChildException) when an operation would violate XML rules.

By eliminating silent failures and invalid intermediate states, XOM allows developers to trust the integrity of any Document or Element instance passed across application boundaries. If an XOM object exists in memory, it is guaranteed to represent valid, well-formed XML.