Package Torello.HTML

Class CommentNode

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable, java.lang.Comparable<CommentNode>
    public final class CommentNode
extends HTMLNode
implements java.lang.CharSequence, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<CommentNode>
    CommentNode - Documentation.

    This is referring to HTML comments which have the form: <!-- This is an HTML-styled COMMENT -->. This node will store the text, and it inherits from class HTMLNode

    The three inherited classes of abstract class HTMLNode are very light-weight, and contain some amount of public methods, but do not have heavy internal-state (either static, or non-static). Below is a list of the internal field's that are added to each of the three instantiations of the ancestor HTMLNode class:

    • class TagNode adds a field public final boolean isClosing - which tells a user if this tag has a forward-slash immediately following the '<' (less-than symbol) at character position 2. This is how one identifies a 'closing-version' of the element, for instance: '</DIV>' and '</SPAN>' would both have their public final boolean isClosing fields set to TRUE. There is also a public final String tok field added to instances of TagNode that identify what html element the TagNode represents. For example an HTML Element such as: <A HREF="http://My.URL.com" TARGET=_blank>, would have it's String 'tok' field set to 'a'

    • class TextNode this inherited class from class HTMLNode does not add any internal state at all. It has the exact same internally-maintained fields as its parent-class. The public final String str field merely states what text this text-node actually represents.

    • class CommentNode for searching-purposes, and ease-of-use, class CommentNode, which is the third and final class to inherit HTMLNode keeps one extra internal-field, which is public final String body. This field is a redundant, duplicate, of the internal string public final String str - which is inherited from the HTML Node class. The subtle difference is that, since comment nodes represent the HTML <!-- and --> symbols, the 'body' of the comment sometimes needs to be searched, quickly. The public final String body leaves off these leading and ending comment delimiter symbols: <!-- and -->

    Below is the inheritance diagram (with fields) of the three concrete-classes that extend the abstract class HTMLNode:

    HTMLNode Inheritance Diagram
    See Also:
    TagNode, TextNode, HTMLNode, Serialized Form




    • Field Detail

      • serialVersionUID

        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final long serialVersionUID = 1;

      • body

        public final java.lang.String body
        This stores a copy of the body of the comment. Specifically, (and simply) the java string method body = str.substring(4, str.length() - 3); is called and stored here. Yes, this does mean that extra memory / double memory is used to store comments, however the trade-offs are somewhat high.

        TRADEOFFS: If the programmer or user ever wishes to perform a search, it becomes obvious that leaving off the beginning and trailing '<!--' and '-->' markers when specifying a search provides more easily readable code, and less error prone code. Thus, when using the CommentNodeFind, Get, Peek, Poll, etc... methods in the package NodeSearch, a Java String substring(...) would have to be invoked on every search comparison loop invocation. Primarily, keeping class HTMLNode and it's descendants all immutable is a much higher priority to ensure clean code, it becomes necessary to keep a redundant copy of the body String.
        Code:
        Exact Field Declaration Expression:
        1
        public final String body;

    • Constructor Detail

      • CommentNode

        public CommentNode​(java.lang.String s)
        This constructor simply makes a call to super(s); a.k.a. class HTML.HTMLNode
        This constructor also checks to ensure that the internal String-field (public final String str) contains beginning and ending comment markers: '<!--' and '-->'

        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
         super(s);

 if (! s.startsWith("<!--")) throw new IllegalArgumentException
     ("The passed HTML string does not start with comment marker '<!--'");

 if (! s.endsWith("-->"))    throw new IllegalArgumentException
     ("The passed HTML string does not end with comment marker '-->'");

 body = str.substring(4, str.length() - 3);

 if (body.contains("-->"))   throw new IllegalArgumentException
     ("The passed HTML string has multiple occurrences of substring '-->'");
        Throws:
        java.lang.IllegalArgumentException - If the passed string does not start and end with the appropriate HTML comment markers: <!-- and -->

    • Method Detail

      • isCommentNode

        public boolean isCommentNode()
        This method identifies that 'this' instance of 'HTMLNode' is, indeed, actually an instance of the (sub-class) CommentNode.
        Overrides:
        isCommentNode in class HTMLNode
        Returns:
        This method shall always return TRUE It overrides the parent-class HTMLNode method isCommentNode(), which always returns FALSE.
        See Also:
        isCommentNode()
        Code:
        Exact Method Body:
        1
         return true;

      • clone

        public CommentNode clone()
        Java's interface Cloneable requirements. This instantiates a new CommentNode with identical String str and String body fields.
        Specified by:
        clone in class HTMLNode
        Returns:
        A new CommentNode whose internal fields are identical to this one.
        Code:
        Exact Method Body:
        1
         return new CommentNode(str);

      • compareTo

        public int compareTo​(CommentNode cn)
        Java's interface Comparable<T> requirements. This does a very simple comparison using the underlying field final String str that all HTMLNode's contain.
        Specified by:
        compareTo in interface java.lang.Comparable<CommentNode>
        Parameters:
        cn - Any other CommentNode to be compared to 'this' CommentNode
        Returns:
        An integer that fulfils Java's interface Comparable<T> public boolean compareTo(T t) method requirements.
        Code:
        Exact Method Body:
        1
         return this.body.compareToIgnoreCase(cn.body);