Class CommentNodePeek


  • public class CommentNodePeek
    extends java.lang.Object
    CommentNode Peek - Documentation.

    CommentNodePeek =>

    1. CommentNode: This implies that TagNode and TextNode elements are ignored completely in this search, and instead, the "comments" between the <!-- and --> symbols - which are all instances of CommentNode, are searched.
    2. Peek: This implies that BOTH the Vector-index / indices where a match occurred, AND the the HTMLNode at that index are SIMULTANEOUSLY returned by these methods - using the data-type classes NodeIndex and SubSection.

    Methods Available

    Method Explanation
    first (...) This will retrieve the first CommentNode match found in the vectorized-page parameter 'html', along with the underlying Vector<HTMLNode> index where this match was found. This object-reference and int are returned as the result, wrapped in the Wrapper-Class CommentNodeIndex.
    nth (...) This will retrieve the nth CommentNode match found in the vectorized-page parameter 'html', along with the underlying Vector<HTMLNode> index where this match was found. This object-reference and int are returned as the result, wrapped in the Wrapper-Class CommentNodeIndex.
    last (...) This will retrieve the last CommentNode match found in the vectorized-page parameter 'html', along with the underlying Vector<HTMLNode> index where this match was found. This object-reference and int are returned as the result, wrapped in the Wrapper-Class CommentNodeIndex.
    nthFromEnd (...) This will retrieve the nth-from-last CommentNode match found in the vectorized-page parameter 'html', along with the underlying Vector<HTMLNode> index where this match was found. This object-reference and int are returned as the result, wrapped in the Wrapper-Class CommentNodeIndex.
    all (...) This will return a Vector<CommentNodeIndex> that contains every CommentNode that matches the specified search-criteria found inside the vectorized-page parameter 'html'. Each match is wrapped in the Wrapper-Class CommentNodeIndex that stores (encapsulates) both the CommentNode object-reference as well as the int index to the HTML Vector where the match was found. These results are then added into the return Vector<CommentNodeIndex>.
    allExcept (...) This will return a Vector<CommentNodeIndex> that contains every CommentNode that does not match the specified search-criteria found inside the vectorized-page parameter 'html'. Each 'un-match' is wrapped in the Wrapper-Class CommentNodeIndex that stores (encapsulates) both the CommentNode object-reference as well as the int index to the HTML Vector where the match was found. These results are then added into the return vector Vector<CommentNodeIndex>.

    Method Parameters

    Parameter Explanation
    Vector<? extends HTMLNode> html This represents any vectorized HTML page, sub-page, or list of partial-elements.
    int nth This represents the 'nth' match of a comparison for-loop. When the method-signature used includes the parameter 'nth' , the first n-1 matches that are found - will be skipped, and the 'nth' match is, instead, returned.

    EXCEPTIONS: An NException shall throw if the value of parameter 'nth' is zero, negative, or larger than the size of the input html-Vector.
    int sPos, int ePos When these parameters are present, only HTMLNode's that are found between the specified Vector indices will be considered for matching with the search criteria.

    NOTE: In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed a negative-value, the internal LV ('Loop Variable Counter') will have its public final int end field set to the length of the vectorized-html page that was passed. (html.size() of parameter Vector<HTMLNode> html).

    EXCEPTIONS: An IndexOutOfBoundsException will be thrown if:

    • If sPos is negative, or if sPos is greater-than or equal-to the size of the input Vector
    • If ePos is zero, or greater than the size of the input Vector.
    • If sPos is a larger integer than ePos
    TextComparitor tc WORKS WITH: This parameter utilizes / works-with parameter String... compareStr to perform the requested comparisons. The comparisons are computed using the String 'body' field of a CommentNode.

    When this parameter is present in the method-signature parameter-list, the decision of whether a CommentNode is to be included in the search result-set is defined by this parameter's FunctionalInterface Predicate 'test' method. TextComparitor is a Java BiPredicate<String, String[]> which compares its first String-parameter against the String's in its second.
    Pattern p These parameters reference Java's "Regular Expression" processing engine. If the method-signature includes the java.util.regex.Pattern parameter, the search-loops will use the standard Regular-Expression Pattern matching routine: p.matcher(comment_node.body).find() when deciding which CommentNode's "match" this search-criteria.
    Predicate<String> p When this parameter is present in the method-signature parameter-list, the decision of whether a CommentNode is to be included in the search result-set are made by the results of the Java Predicate.test(String) method.

    Specifically: p.test(comment_node.body)
    String... compareStr WORKS WITH: This parameter works in coordination with the TextComparitor tc parameter. This parameter supplies the String's with which the comparisons of the CommentNode.body field may be compared.

    Return Values:

    1. CommentNodeIndex represents a matched CommentNode, and it's position/vector-index, from the html vectorized-page parameter 'html'
    2. A return value of null implies no matches were found.
    3. Vector<CommentNodeIndex> - A vector of CommentNodeIndex represents all matches from the vectorized-page parameter 'html'. The class CommentNodeIndex is a return-value way of encapsulating both the CommentNode and it's index into the underlying HTMLNode Vector.
    4. A zero-length Vector<CommentNodeIndex> means no matches were found on the page or sub-page. Empty Vectors are returned from any method where the possibility existed for multiple-matches being provided as a result-set.


    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Internal-State: A user may click on this class' source code (see link below) to view any and all internally defined fields class. A cursory inspection of the code would prove that this class has precisely zero internally defined global fields (Spaghetti). All variables used by the methods in this class are local fields only, and therefore this class ought to be though of as 'state-less'.

    View Actual Hi-Lited Code Files: