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

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