Package eu.maveniverse.domtrip

Class Node

  • Direct Known Subclasses:
    Comment, ContainerNode, ProcessingInstruction, Text
    public abstract class Node
extends java.lang.Object
    Base class for all XML nodes in the lossless XML tree, providing core functionality for formatting preservation and tree navigation.

    The Node class serves as the foundation for DomTrip's type-safe XML node hierarchy. It provides essential functionality for maintaining parent-child relationships, tracking modifications, and preserving whitespace formatting during round-trip parsing and serialization.

    Node Hierarchy:

    Core Functionality:

    • Whitespace Preservation - Maintains preceding and following whitespace
    • Modification Tracking - Tracks changes for selective formatting preservation
    • Parent-Child Relationships - Maintains bidirectional tree navigation

    Usage Example:

    
 // Access node properties
 NodeType type = node.getNodeType();
 ContainerNode parent = node.parent();
 Element parentElement = node.getParentElement();
 Document document = node.document();
 int depth = node.getDepth();

 // Check modification status
 if (node.isModified()) {
     // Node has been changed since parsing
 }

 // Serialize to XML
 String xml = node.toXml();
    See Also:
    ContainerNode, Element, Text, Comment, ProcessingInstruction

    • Field Detail

      • parent

        protected ContainerNode parent
        The parent node of this node in the XML tree

      • precedingWhitespace

        protected java.lang.String precedingWhitespace
        Whitespace that appears before this node in the original XML

      • modified

        protected boolean modified
        Flag indicating whether this node has been modified since parsing

    • Constructor Detail

      • Node

        protected Node()
        Creates a new XML node with default settings.

        Initializes the node with empty whitespace strings and sets the modification flag to false.

    • Method Detail

      • type

        public abstract Node.NodeType type()
        Returns the type of this XML node.

        The node type determines the node's behavior and capabilities. This method must be implemented by all concrete node classes.

        Returns:
        the Node.NodeType of this node

      • toXml

        public java.lang.String toXml()
        Serializes this node to an XML string.

        Creates a complete XML representation of this node and its children (if any), preserving original formatting for unmodified content.

        Returns:
        the XML string representation of this node
        See Also:
        toXml(StringBuilder)

      • toXml

        public abstract void toXml​(java.lang.StringBuilder sb)
        Serializes this node to XML, appending to the provided StringBuilder.

        This method is more efficient than toXml() when building larger XML documents as it avoids string concatenation overhead.

        Parameters:
        sb - the StringBuilder to append the XML content to
        See Also:
        toXml()

      • copy

        public abstract Node copy()
        Creates a deep copy of this node.

        The copied node will have:

        • All properties copied from the original
        • All child nodes recursively copied (for container nodes)
        • Whitespace and formatting properties preserved
        • No parent (parent is set to null)

        The copied node and its descendants will have their parent-child relationships properly established within the copied subtree.

        Returns:
        a new node that is a deep copy of this node
        Since:
        1.1.0

      • clone

        @Deprecated
public Node clone()
        Deprecated.
        Use copy() instead.
        Creates a deep copy of this node.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a new node that is a deep copy of this node

      • parent

        public ContainerNode parent()
        Gets the parent container node of this node.

        Returns the parent container node in the XML tree, or null if this is the root node or if the node has not been added to a tree. Only Document and Element nodes can be parents since they are the only container nodes.

        Returns:
        the parent container node, or null if this node has no parent
        See Also:
        parentElement(), document()

      • parent

        public Node parent​(ContainerNode parent)
        Sets the parent container node of this node.

        This method is typically called automatically when adding nodes to containers. Manual use should be done carefully to maintain tree consistency.

        Parameters:
        parent - the parent container node to set, or null to clear the parent
        Returns:
        this node for method chaining
        See Also:
        parent()

      • precedingWhitespace

        public java.lang.String precedingWhitespace()
        Gets the whitespace that precedes this node in the original XML.

        This includes any whitespace characters (spaces, tabs, newlines) that appeared before this node in the source XML. Preserving this whitespace enables lossless round-trip processing.

        Returns:
        the preceding whitespace string, never null
        See Also:
        precedingWhitespace(String)

      • precedingWhitespace

        public Node precedingWhitespace​(java.lang.String whitespace)
        Sets the whitespace that precedes this node.

        This method allows control over the whitespace formatting before this node when serializing to XML.

        Parameters:
        whitespace - the whitespace string to set, null is treated as empty string
        Returns:
        this node for method chaining
        See Also:
        precedingWhitespace()

      • isModified

        public boolean isModified()

      • markModified

        public void markModified()

      • clearModified

        public void clearModified()

      • parentElement

        public Element parentElement()
        Gets the Element parent of this node.

        Returns the parent if it's an Element, or null if the parent is a Document or if this node has no parent. Since parents can only be Element or Document, no traversal is needed.

        Returns:
        the Element parent, or null if parent is Document or no parent exists
        See Also:
        parent(), document()

      • document

        public Document document()
        Gets the Document that contains this node.

        Recursively traverses up the tree to find the root Document node. Every node in a properly constructed XML tree should have a Document as its ultimate parent.

        Returns:
        the Document containing this node, or null if not in a document tree
        See Also:
        parent(), parentElement()

      • depth

        public int depth()
        Gets the depth of this node in the tree (root is 0).

      • isDescendantOf

        public boolean isDescendantOf​(Node ancestor)
        Checks if this node is a descendant of the given node.

      • siblingIndex

        public int siblingIndex()
        Gets the index of this node within its parent's children list.
        Returns:
        the index of this node, or -1 if this node has no parent

      • previousSibling

        public java.util.Optional<Node> previousSibling()
        Gets the previous sibling node.
        Returns:
        an Optional containing the previous sibling, or empty if this is the first child or has no parent

      • nextSibling

        public java.util.Optional<Node> nextSibling()
        Gets the next sibling node.
        Returns:
        an Optional containing the next sibling, or empty if this is the last child or has no parent

      • previousSiblingElement

        public java.util.Optional<Element> previousSiblingElement()
        Gets the previous sibling that is an Element.
        Returns:
        an Optional containing the previous Element sibling, or empty if none exists

      • accept

        public abstract DomTripVisitor.Action accept​(DomTripVisitor visitor)
        Accepts a visitor for depth-first tree traversal.

        This method implements the visitor pattern, allowing structured traversal of the XML tree with enter/exit lifecycle callbacks. Each node type dispatches to the appropriate visitor method.

        Parameters:
        visitor - the visitor to accept
        Returns:
        the action returned by the visitor, indicating how traversal should proceed
        Throws:
        java.lang.IllegalArgumentException - if visitor is null
        Since:
        1.3.0
        See Also:
        DomTripVisitor

      • nextSiblingElement

        public java.util.Optional<Element> nextSiblingElement()
        Gets the next sibling that is an Element.
        Returns:
        an Optional containing the next Element sibling, or empty if none exists