Package eu.maveniverse.domtrip

Class 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:
    Node, ProcessingInstruction

    • Constructor Detail

      • Comment

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

    • Method Detail

      • content

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

        Returns the text content without the surrounding comment delimiters.

        Returns:
        the comment content
        See Also:
        content(String)

      • 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:
        Node.parent()

      • precedingWhitespace

        public Comment 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 comment for method chaining
        See Also:
        Node.precedingWhitespace()

      • content

        public Comment content​(java.lang.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:
        content()

      • toXml

        public void toXml​(java.lang.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:
        Node.toXml()

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

      • 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:
        isWhitespaceOnly()

      • 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 java.lang.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 java.lang.Object
        Returns:
        a string representation of this comment

      • of

        public static Comment of​(java.lang.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