Package eu.maveniverse.domtrip

package eu.maveniverse.domtrip

DomTrip - A lossless XML processing library for Java.

This package provides a comprehensive XML processing library that preserves all formatting information including whitespace, comments, processing instructions, attribute quote styles, and entity references during round-trip parsing and serialization.

Key Features

• Lossless Processing - Preserves exact formatting for unmodified content
• Attribute Quote Preservation - Maintains single vs double quotes
• Whitespace Preservation - Keeps original indentation and spacing
• Entity Preservation - Maintains entity references in original form
• Comment Preservation - Preserves XML comments and processing instructions
• Namespace Support - Comprehensive namespace handling with resolution and context management
• Builder Patterns - Fluent APIs for creating XML structures
• Type Safety - Enums for quote styles and whitespace patterns

Type-Safe Node Hierarchy

• Node - Base class for all XML nodes
• ContainerNode - Abstract base for nodes that can contain children
• Document - Root XML document (extends ContainerNode)
• Element - XML elements with attributes and namespace support (extends ContainerNode)
• Text - Text content nodes (leaf node)
• Comment - XML comment nodes (leaf node)
• ProcessingInstruction - Processing instruction nodes (leaf node)

Core Services

• Editor - High-level API for XML editing
• NamespaceContext - Namespace resolution and context management
• NamespaceResolver - Namespace utility methods
• DomTripConfig - Configuration options
• Serializer - XML serialization

Usage Example

// Parse XML while preserving formatting
Document doc = Document.of(xmlString);
Editor editor = new Editor(doc);

// Make modifications
Element root = editor.root();
editor.addElement(root, "newChild", "content");

// Serialize with preserved formatting
String result = editor.toXml();

// Use configuration for different output styles
String prettyXml = editor.toXml(DomTripConfig.prettyPrint());
String minimalXml = editor.toXml(DomTripConfig.minimal());

Configuration

Use DomTripConfig to control parsing and serialization behavior:

DomTripConfig config = DomTripConfig.defaults()
    .withCommentPreservation(true)
    .withPrettyPrint(false);

Document doc = Document.of(xmlString);
Editor editor = new Editor(doc, config);

Namespace Support

DomTrip provides comprehensive namespace handling:

// Create elements with namespaces using QName
QName soapEnvelope = QName.of("http://schemas.xmlsoap.org/soap/envelope/", "Envelope", "soap");
Element envelope = Element.of(soapEnvelope);

// Namespace-aware navigation
Optional<Element> body = root.descendant(
    QName.of("http://schemas.xmlsoap.org/soap/envelope/", "Body"));

// Namespace resolution
String namespaceURI = element.namespaceURI();
String localName = element.localName();
String prefix = element.prefix();

Thread Safety

All types in this package are not thread-safe. The DOM tree uses mutable state and lazy materialization with no synchronization, consistent with standard DOM APIs (e.g., org.w3c.dom). External synchronization is required for concurrent access to any node in a DOM tree. Parser instances also use mutable state to track parse position and must not be shared across threads concurrently, but may be reused sequentially.

Version:

1.0

Related Packages

Package	Description
eu.maveniverse.domtrip.sax
eu.maveniverse.domtrip.stax

Class	Description
Attribute	Represents an XML attribute with complete formatting preservation including quote styles, whitespace, and entity encoding.
ChangeType	Enumerates the types of changes that can be detected between two XML documents.
Comment	Represents an XML comment node, preserving exact formatting and content.
ContainerNode	Abstract base class for Document and Element nodes that can contain child nodes.
DiffConfig	Configuration for XML diff operations.
DiffConfig.Builder	Builder for DiffConfig.
DiffResult	The result of comparing two XML documents, containing all detected changes.
Document	Represents the root of an XML document, containing the document element and preserving document-level formatting like XML declarations and DTDs.
DomTripConfig	Configuration options for controlling DomTrip XML processing behavior.
DomTripException	Base exception class for all DomTrip-related errors.
DomTripVisitor	Visitor interface for structured depth-first tree traversal with enter/exit lifecycle callbacks.
DomTripVisitor.Action	Controls traversal flow during a visitor walk.
Editor	High-level API for editing XML documents while preserving original formatting.
Editor.EditorCommentBuilder	Builder for creating comments within the Editor context.
Editor.EditorElementBuilder	Builder for creating and configuring elements within the Editor context.
Editor.EditorTextBuilder	Builder for creating text nodes within the Editor context.
Editor.NodeBuilder	Fluent builder for creating and adding nodes to the document.
Element	Represents an XML element with attributes and children, preserving original formatting including attribute spacing, quote styles, and element structure.
ElementQuery	Fluent API for querying and filtering XML elements.
EmptyElementStyle	Enumeration for XML empty element formatting styles.
NamespaceContext	Represents a namespace context for XML elements, providing namespace URI resolution and prefix management functionality.
NamespaceResolver	Utility class for resolving namespace information in XML elements.
Node	Base class for all XML nodes in the lossless XML tree, providing core functionality for formatting preservation and tree navigation.
Node.NodeType	Enumeration of XML node types supported by DomTrip.
Parser	A lossless XML parser that preserves all formatting information including whitespace, comments, attribute quote styles, and entity encoding.
ProcessingInstruction	Represents an XML processing instruction, preserving exact formatting and content.
QName	Represents a qualified XML name with namespace URI, local name, and optional prefix.
QuoteStyle	Enumeration for XML attribute quote styles, supporting both single and double quotes.
Serializer	Serializes XML node trees back to XML string format with configurable formatting options and lossless preservation for unmodified content.
Text	Represents text content in XML documents, preserving exact whitespace, entity encoding, and CDATA section formatting.
TreeWalker	Lambda-friendly builder for configuring and executing tree traversals.
XmlChange	Represents a single change detected between two XML documents.
XmlDiff	XML-aware structural diff engine that compares two documents and detects both semantic and formatting-only changes.
XPathExpression	Mini-XPath expression support for string-based element queries.