Class Node

java.lang.Object
eu.maveniverse.domtrip.Node
Direct Known Subclasses:
Comment, ContainerNode, ProcessingInstruction, Text
public abstract class Node extends 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:

  • Field Details

    • parent

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

    • precedingWhitespace

      protected 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 Details

    • 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 Details

    • 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 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

      public abstract void toXml(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:

    • 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 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:

    • 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:

    • precedingWhitespace

      public 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

      public Node precedingWhitespace(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:

    • 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:

    • 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:

    • 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 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 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 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:
      IllegalArgumentException - if visitor is null
      Since:
      1.3.0
      See Also:

    • nextSiblingElement

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