Class Text

java.lang.Object
eu.maveniverse.domtrip.Node
eu.maveniverse.domtrip.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:

  • Constructor Details

    • Text

      public Text(String content)

    • Text

      public Text(String content, boolean isCData)

    • Text

      public Text(String content, String rawContent)

  • Method Details

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

    • precedingWhitespace

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

      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:

    • content

      public Text content(String content)

    • rawContent

      public String rawContent()

    • rawContent

      public Text rawContent(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:

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

    • leadingWhitespace

      public 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

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

    • contentPreservingWhitespace

      public Text contentPreservingWhitespace(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:

    • hasLeadingWhitespace

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

    • hasTrailingWhitespace

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

    • toXml

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

    • unescapeTextContent

      public static String unescapeTextContent(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 String toString()
      Overrides:
      toString in class Object

    • of

      public static Text of(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(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(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