Package eu.maveniverse.domtrip

Class Text

  • public class Text
extends Node
    Represents text content in XML documents, preserving exact whitespace, entity encoding, and CDATA section formatting.

    The Text class handles all forms of textual content in XML documents, including regular text nodes, CDATA sections, and whitespace-only content. It maintains both the decoded text content and the original raw content with entities preserved, enabling lossless round-trip processing.

    Text Handling:

    • Entity Preservation - Maintains original entity encoding
    • CDATA Support - Handles CDATA sections
    • Whitespace Preservation - Preserves significant whitespace
    • Content Normalization - Optional whitespace normalization

    Content Types:

    • Regular Text - Standard text content with entity escaping
    • CDATA Sections - Unescaped text within CDATA blocks
    • Whitespace - Formatting whitespace between elements

    Usage Examples:

    
 // Create regular text content
 Text text = new Text("Hello & welcome!");

 // Create using factory methods
 Text factoryText = Text.of("Hello World");
 Text cdataText = Text.cdata("<script>alert('test');</script>");
 Text explicitCdata = Text.of("content", true);

 // Create and modify with fluent API
 Text fluentText = Text.of("Regular text").asCData();
 Text preservedText = Text.of("  spaces  ").preserveWhitespace(false);

 // Check content properties
 if (text.isWhitespaceOnly()) {
     // Handle formatting whitespace
 }

 // Access both decoded and raw content
 String content = text.content();     // "Hello & welcome!"
 String raw = text.getRawContent();      // "Hello &amp; welcome!" (if preserved)

    Entity Handling:

    Text nodes automatically handle XML entity encoding and decoding:

    • &amp; ↔ &
    • &lt; ↔ <
    • &gt; ↔ >
    • &quot; ↔ "
    • &apos; ↔ '
    See Also:
    Node, Element, Comment

    • Constructor Detail

      • Text

        public Text​(java.lang.String content)

      • Text

        public Text​(java.lang.String content,
            boolean isCData)

      • Text

        public Text​(java.lang.String content,
            java.lang.String rawContent)

    • Method Detail

      • type

        public Node.NodeType type()
        Description copied from class: Node
        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.

        Specified by:
        type in class Node
        Returns:
        the Node.NodeType of this node

      • content

        public java.lang.String content()

      • parent

        public Text 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.

        Overrides:
        parent in class Node
        Parameters:
        parent - the parent container node to set, or null to clear the parent
        Returns:
        this text node for method chaining
        See Also:
        Node.parent()

      • precedingWhitespace

        public Text 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.

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

      • content

        public Text content​(java.lang.String content)

      • rawContent

        public java.lang.String rawContent()

      • rawContent

        public Text rawContent​(java.lang.String rawContent)

      • cdata

        public boolean cdata()

      • cdata

        public Text cdata​(boolean cData)

      • preserveWhitespace

        public boolean preserveWhitespace()

      • preserveWhitespace

        public Text preserveWhitespace​(boolean preserveWhitespace)

      • accept

        public 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.

        Specified by:
        accept in class Node
        Parameters:
        visitor - the visitor to accept
        Returns:
        the action returned by the visitor, indicating how traversal should proceed
        Since:
        1.3.0
        See Also:
        DomTripVisitor

      • isWhitespaceOnly

        public boolean isWhitespaceOnly()
        Returns true if this text node contains only whitespace

      • isEmpty

        public boolean isEmpty()
        Returns true if this text node is empty

      • trimmedContent

        public java.lang.String trimmedContent()
        Gets the text content with leading and trailing whitespace removed.

        This is a convenience method that returns the trimmed content without modifying the original content. The original content with whitespace is preserved for lossless round-trip processing.

        Returns:
        the content with leading and trailing whitespace removed
        See Also:
        content(), leadingWhitespace(), trailingWhitespace()

      • leadingWhitespace

        public java.lang.String leadingWhitespace()
        Gets the leading whitespace from the text content.

        Extracts and returns any whitespace characters (spaces, tabs, newlines) that appear at the beginning of the content. This is useful for understanding the whitespace structure without modifying the original content.

        Returns:
        the leading whitespace, or empty string if none
        See Also:
        trailingWhitespace(), trimmedContent()

      • trailingWhitespace

        public java.lang.String trailingWhitespace()
        Gets the trailing whitespace from the text content.

        Extracts and returns any whitespace characters (spaces, tabs, newlines) that appear at the end of the content. This is useful for understanding the whitespace structure without modifying the original content.

        Returns:
        the trailing whitespace, or empty string if none
        See Also:
        leadingWhitespace(), trimmedContent()

      • contentPreservingWhitespace

        public Text contentPreservingWhitespace​(java.lang.String newContent)
        Sets new content while preserving the existing whitespace pattern.

        This method replaces the actual content but maintains the same leading and trailing whitespace as the original content. This is useful when you want to update the meaningful content without affecting the formatting.

        Example:

        
 // Original: "   Hello World   "
 text.contentPreservingWhitespace("Goodbye");
 // Result:   "   Goodbye   "
        Parameters:
        newContent - the new content to set (will be placed between existing whitespace)
        See Also:
        content(String), leadingWhitespace(), trailingWhitespace()

      • hasLeadingWhitespace

        public boolean hasLeadingWhitespace()
        Checks if the content has leading whitespace.
        Returns:
        true if the content starts with whitespace characters
        See Also:
        hasTrailingWhitespace(), leadingWhitespace()

      • hasTrailingWhitespace

        public boolean hasTrailingWhitespace()
        Checks if the content has trailing whitespace.
        Returns:
        true if the content ends with whitespace characters
        See Also:
        hasLeadingWhitespace(), trailingWhitespace()

      • toXml

        public void toXml​(java.lang.StringBuilder sb)
        Appends this text node's XML representation to the provided StringBuilder. The method writes the node's preceding whitespace, then either: - serializes the content as a CDATA section when this node is marked as CDATA, or - appends the raw, unescaped content if available and the node has not been modified, otherwise appends the escaped text content.
        Specified by:
        toXml in class Node
        Parameters:
        sb - the StringBuilder to append XML output to
        See Also:
        Node.toXml()

      • unescapeTextContent

        public static java.lang.String unescapeTextContent​(java.lang.String text)
        Unescapes XML entities in text content, including numeric character references.
        Parameters:
        text - the text possibly containing XML entities or numeric references
        Returns:
        the text with entities and numeric references decoded; empty string when text is null

      • trim

        public void trim()
        Trims whitespace from the content while preserving internal structure

      • normalizeWhitespace

        public void normalizeWhitespace()
        Normalizes whitespace in the content (collapses multiple spaces to single space)

      • copy

        public Text 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.

        Specified by:
        copy in class Node
        Returns:
        a new node that is a deep copy of this node
        Since:
        1.1.0

      • clone

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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • of

        public static Text of​(java.lang.String content)
        Creates a text node with the specified content.

        Factory method following modern Java naming conventions.

        Parameters:
        content - the text content
        Returns:
        a new Text node

      • cdata

        public static Text cdata​(java.lang.String content)
        Creates a CDATA text node with the specified content.

        Factory method for creating CDATA sections.

        Parameters:
        content - the CDATA content
        Returns:
        a new Text node with CDATA flag set

      • of

        public static Text of​(java.lang.String content,
                      boolean isCData)
        Creates a text node with the specified content and CDATA flag.

        Factory method for creating text nodes with explicit CDATA control.

        Parameters:
        content - the text content
        isCData - true to create a CDATA section, false for regular text
        Returns:
        a new Text node

      • asCData

        public Text asCData()
        Converts this text node to a CDATA section.

        Fluent setter for converting existing text to CDATA format.

        Returns:
        this text node for method chaining