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>
    Concrete HTMLNode SubClasses:
    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 -->
    Represents HTML Comments, and is one of only three HTML Element Classes provided by the Java HTML Library Tool, and also one of the three data-classes that can be generated by the HTML Parser.

    This is referring to HTML comments which have the form: <!-- This is an HTML-styled COMMENT -->. This node will store such text in the parent-class field: str

    This class inherits from abstract parent-class HTMLNode


    Inheritance Tree Diagram:
    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:
         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.

        Trade Off:
        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:
         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 '-->'
        Throws:
        java.lang.IllegalArgumentException - If the passed string does not start and end with the appropriate HTML comment-markers: <!-- and -->
        Code:
        Exact Constructor Body:
         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 '-->'");

    • Method Detail

      • isCommentNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean isCommentNode()
        This method identifies that 'this' instance of (abstract parent-class) HTMLNode is, indeed, an instance of sub-class CommentNode.

        Final Method:
        This method is final, and cannot be modified by sub-classes.
        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:
         return true;

      • ifCommentNode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final CommentNode ifCommentNode()
        This method identifies that 'this' instance of (abstract parent-class) HTMLNode is, indeed, an instance of sub-class CommentNode.

        Final Method:
        This method is final, and cannot be modified by sub-classes.
        Overrides:
        ifCommentNode in class HTMLNode
        Returns:
        'this' reference. This method can be used inside loops for improving the readability of loop-condition expressions. See example below:

        Example:
         Vector<HTMLNode> fileVec = HTMLPage.getPageTokens(new URL("http://some.url.com"), false);
 CommentNode c;
 
 // NOTE: The casting to class CommentNode is automatically acheived with this method,
 //       which can make loops a lot easier to read.  Only a CommentNode instance will have 
 //       a '.body' field.  Attempting to read a '.body' field from an instance of HTMLNode
 //       would immediately generate a compile-time error.
 
 for (HTMLNode n : fileVec)
     if ((c = myHTMLVector.elementAt(i).ifCommentNode()) != null)
         if (c.body.equals("Some Comment Node Text"))
             ...


        This method-version overrides the parent-class-version, which always returns null. This method is not overriden by other HTMLNode sub-classes.
        See Also:
        ifCommentNode()
        Code:
        Exact Method Body:
         return this;

      • 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:
         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:
         return this.body.compareToIgnoreCase(cn.body);