Class Comment

java.lang.Object
eu.maveniverse.domtrip.Node
eu.maveniverse.domtrip.Comment
public class Comment extends Node
Represents an XML comment node, preserving exact formatting and content.

XML comments are used to include human-readable notes and documentation within XML documents. DomTrip preserves comments exactly as they appear in the source XML, including any internal formatting, whitespace, and content.

Comment Handling:

  • Content Preservation - Maintains exact comment text
  • Position Preservation - Keeps comments in their original locations
  • Whitespace Preservation - Preserves surrounding whitespace

XML Comment Syntax:

XML comments follow the syntax: <!-- comment content -->

Comments cannot contain the string "--" and cannot end with "-".

Usage Examples:

// Create a comment
Comment comment = new Comment("This is a comment");

// Create using factory method
Comment factoryComment = Comment.of("This is a factory comment");

// Create and modify with fluent API
Comment fluentComment = Comment.of("Initial content")
    .content("Updated content");

// Add to document
document.addChild(comment);

// Check comment properties
if (comment.isEmpty()) {
    // Handle empty comment
}

if (comment.isWhitespaceOnly()) {
    // Handle whitespace-only comment
}

Best Practices:

  • Avoid using "--" within comment content
  • Use comments for documentation and metadata
  • Consider comment placement for readability
See Also:

  • Constructor Details

    • Comment

      public Comment(String content)
      Creates a new XML comment with the specified content.
      Parameters:
      content - the comment content (without the delimiters)

  • Method Details

    • type

      public Node.NodeType type()
      Returns the node type for this comment.
      Specified by:
      type in class Node
      Returns:
      Node.NodeType.COMMENT

    • content

      public String content()
      Gets the content of this comment.

      Returns the text content without the surrounding comment delimiters.

      Returns:
      the comment content
      See Also:

    • parent

      public Comment 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 comment for method chaining
      See Also:

    • precedingWhitespace

      public Comment 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 comment for method chaining
      See Also:

    • content

      public Comment content(String content)
      Sets the content of this comment.

      Setting the content marks this comment as modified. The content should not include the comment delimiters ().

      Parameters:
      content - the new comment content, or null for empty content
      See Also:

    • toXml

      public void toXml(StringBuilder sb)
      Serializes this comment to XML, appending to the provided StringBuilder.

      Appends the complete comment including preceding whitespace, comment delimiters, content, and following whitespace.

      Specified by:
      toXml in class Node
      Parameters:
      sb - the StringBuilder to append the XML content to
      See Also:

    • 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()
      Checks if this comment contains only whitespace characters.

      Returns true if the comment content consists entirely of whitespace characters (spaces, tabs, newlines, etc.).

      Returns:
      true if the comment contains only whitespace, false otherwise
      See Also:

    • isEmpty

      public boolean isEmpty()
      Checks if this comment is completely empty.

      Returns true if the comment has no content at all.

      Returns:
      true if the comment is empty, false otherwise
      See Also:

    • copy

      public Comment 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 Comment clone()
      Deprecated.
      Use copy() instead.
      Creates a deep copy of this comment.
      Overrides:
      clone in class Node
      Returns:
      a new comment that is a copy of this comment

    • toString

      public String toString()
      Returns a string representation of this comment for debugging purposes.

      The string includes the comment content, truncated if longer than 50 characters, with newlines escaped for readability.

      Overrides:
      toString in class Object
      Returns:
      a string representation of this comment

    • of

      public static Comment of(String content)
      Creates a comment with the specified content.

      Factory method following modern Java naming conventions.

      Parameters:
      content - the comment content
      Returns:
      a new Comment