Class TagNodePoll


  • public class TagNodePoll
    extends java.lang.Object
    TagNode Poll - Documentation.

    TagNodePoll =>

    1. TagNode: This implies that only HTML TagNode's will be used for searching. The field TagNode.tok field is used as a search criteria. This public, final String field contains the name of the HTML Element - for instance, 'div', 'p', 'span', 'img', etc...
      InnerTag's - (a.k.a. 'attributes') - are not part of the search.
    2. Poll: This refers to the operation of both removing and returning node matches to the programmer. After a 'poll' operation, the initial vectorized-html will actually contain fewer elements - and the removed elements shall be returned to the calling method.

    Methods Available

    Method Explanation
    first (...) This will 1) find, 2) remove, and then 3) return (a procedure that here is known as 'polling') the first TagNode match-by-html-token found on the vectorized-page parameter 'html'.
    nth (...) This will 1) find, 2) remove, and then 3) return (a procedure that here is known as 'polling') the nth TagNode match-by-html-token found on the vectorized-page parameter 'html'.
    last (...) This will 1) find, 2) remove, and then 3) return the last TagNode match (according to the String TagNode.tok and the boolean TagNode.isClosing fields) found on the vectorized-page parameter 'html'.
    nthFromEnd (...) This will 1) find, 2) remove, and then 3) return the nthFromEnd TagNode match (according to the the String TagNode.tok and the boolean TagNode.isClosing fields) found on the vectorized-page parameter 'html'.
    all (...) This will 'poll' every TagNode match (according to the String TagNode.tok and the boolean TagNode.isClosing fields) found on the vectorized-page parameter 'html'.
    allExcept (...) This will 'poll' every TagNode which does not match (according to the String TagNode.tok and the boolean TagNode.isClosing fields) found on the vectorized-page parameter 'html'.

    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
    TC tagCriteria The three values of enumeration TC are: TC.OpeningTags, TC.ClosingTags and TC.Both. These values specify a search-criteria result set for an HTML TagNode. There are two types of HTML Elements:

    • "opening versions" of the HTML-tag such as: <A HREF="...">
    • "closing versions" of the element such as: </A>.

    NOTE: If parameter 'tagCriteria' is passed a value of TC.Both, then (and this is hopefully obvious), that both 'opening' and 'closing' versions of the tag will be considered to meet / match the search criteria.
    String... htmlTags When this parameter is present, only HTMLNode's which are both instances of class TagNode *and* whose TagNode.tok field String-value matches (is equal to) at least one of the elements in this VarArgs String parameter-set will be considered for a match.

    COMMON EXAMPLES: Some common examples of valid htmlTags are: a, div, img, table, tr, meta as well as all other valid HTML element-tokens.

    NOTE: This comparison is performed using a case-insensitive compare-method

    EXCEPTIONS: If even one of the elements in this parameter-set is an invalid HTML token, an HTMLTokException will be thrown.

    Return Values:

    1. TagNode represents a matched TagNode from the html vectorized-page parameter 'html' - after having been removed from the underlying vector, first
    2. A return value of null implies no matches were found, and no nodes were removed.
    3. Vector<TagNode> - A vector of TagNode represent all matches from the vectorized-page parameter 'html' - all of which were also removed from the underlying vector.
    4. A zero-length Vector<TagNode> means no matches were found on the page or sub-page. This also means that the original-input vector shall remain unchanged, and no nodes have been removed. 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:






    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static Vector<TagNode> all​(Vector<? extends HTMLNode> html, int sPos, int ePos, TC tagCriteria, String... htmlTags)
      static Vector<TagNode> all​(Vector<? extends HTMLNode> html, TC tagCriteria, String... htmlTags)
      static Vector<TagNode> allExcept​(Vector<? extends HTMLNode> html, int sPos, int ePos, TC tagCriteria, String... htmlTags)
      static Vector<TagNode> allExcept​(Vector<? extends HTMLNode> html, TC tagCriteria, String... htmlTags)
      static TagNode first​(Vector<? extends HTMLNode> html, int sPos, int ePos, TC tagCriteria, String... htmlTags)
      static TagNode first​(Vector<? extends HTMLNode> html, TC tagCriteria, String... htmlTags)
      static TagNode last​(Vector<? extends HTMLNode> html, int sPos, int ePos, TC tagCriteria, String... htmlTags)
      static TagNode last​(Vector<? extends HTMLNode> html, TC tagCriteria, String... htmlTags)
      static TagNode nth​(Vector<? extends HTMLNode> html, int nth, int sPos, int ePos, TC tagCriteria, String... htmlTags)
      static TagNode nth​(Vector<? extends HTMLNode> html, int nth, TC tagCriteria, String... htmlTags)
      static TagNode nthFromEnd​(Vector<? extends HTMLNode> html, int nth, int sPos, int ePos, TC tagCriteria, String... htmlTags)
      static TagNode nthFromEnd​(Vector<? extends HTMLNode> html, int nth, TC tagCriteria, String... htmlTags)
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait