Class TagNodePeekInclusive

  • public class TagNodePeekInclusive
extends java.lang.Object
    TagNodePeekInclusive 🠞
    1. TagNode: This implies that only HTML TagaNode'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. 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.

    3. Inclusive: The word "Inclusive" is used to indicate that all HTMLNode's between an opening and closing HTML-tag are requested. The concept is extremely similar to the Java-Script feature / term '.innerHTML', although in this (JavaHTML) JAR Library, no DOM-Trees are ever constructed. This method will PEEK for all nodes between a matching, opening, TagNode element, and its corresponding-closing TagNode.
    Searches for TagNode matches, using exactly the same criteria offered by class TagNodePeek, but also retrieves the corresponding Closing-Tag from the Vector, and returns them, all nodes & between them, and their corresponding Vector-index locations as a SubSection.

    Methods Available

    Method Explanation
    first (...) This will retrieve the first SubSection that meet the specified criteria. The sub-list is copied out of the passed vectorized-html web-page 'html'. Since this is a 'Peek' operation, it is important to note that class SubSection has fields for both the Vector<HTMLNode> sub-list of nodes, and a field for class DotPair which are integer index-pointers into the original web-page Vector.
    nth (...) This will retrieve the nth SubSection that meet the specified criteria. The sub-list is copied out of the passed vectorized-html web-page 'html'. Since this is a 'Peek' operation, it is important to note that class SubSection has fields for both the Vector<HTMLNode> sub-list of nodes, and a field for class DotPair which are integer index-pointers into the original web-page Vector.
    last (...) This will retrieve the last SubSection that meet the specified criteria. The sub-list is copied out of the passed vectorized-html web-page 'html'. Since this is a 'Peek' operation, it is important to note that class SubSection has fields for both the Vector<HTMLNode> sub-list of nodes, and a field for class DotPair which are integer index-pointers into the original web-page Vector.
    nthFromEnd (...) This will retrieve the nthFromEnd SubSection that meet the specified criteria. The sub-list is copied out of the passed vectorized-html web-page 'html'. Since this is a 'Peek' operation, it is important to note that class SubSection has fields for both the Vector<HTMLNode> sub-list of nodes, and a field for class DotPair which are integer index-pointers into the original web-page Vector.
    all (...) Retrieves every sub-list or sub-page, returned as Vector<SubSection>, copied out of the passed-parameter html-page or sub-page 'html' for each TagNode, and it's closing-tag pair, that meet the specified criteria.
    allExcept (...) Retrieves every sub-list or sub-page, returned as Vector<SubSection>, copied out of the passed-parameter html-page or sub-page 'html' for each TagNode, and it's closing-tag pair, that that do not meet the specified criteria.

    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. SubSection This is a sub-set or sub-list that matches the search-criteria from the html vectorized-page parameter 'html'
    2. A return value of null implies no matching sub-lists or sub-pages were found.
    3. Vector<SubSection> This would be a "list of sub-lists" or an "array of sub-arrays" which are used when multiple results (multiple sub-lists) are needed to be returned to the calling procedure.
    4. A zero-length Vector<SubSection> vector means no matches were found on the page or sub-page. Zero-length vectors are returned from any method where the possibility existed for multiple-matches being provided as a result-set.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 12 Method(s), 12 declared static
    • 0 Field(s)


    • Method Summary

       
      All Matches
      Modifier and Type Method
      static Vector<SubSection> all​(Vector<? extends HTMLNode> html, String... htmlTags)
       
      All Matches, Range Limited
      Modifier and Type Method
      static Vector<SubSection> all​(Vector<? extends HTMLNode> html, int sPos, int ePos, String... htmlTags)
       
      All Non-Matches
      Modifier and Type Method
      static Vector<SubSection> allExcept​(Vector<? extends HTMLNode> html, String... htmlTags)
       
      All Non-Matches, Range Limited
      Modifier and Type Method
      static Vector<SubSection> allExcept​(Vector<? extends HTMLNode> html, int sPos, int ePos, String... htmlTags)
       
      First Match
      Modifier and Type Method
      static SubSection first​(Vector<? extends HTMLNode> html, String... htmlTags)
       
      First Match, Range Limited
      Modifier and Type Method
      static SubSection first​(Vector<? extends HTMLNode> html, int sPos, int ePos, String... htmlTags)
       
      Last Match
      Modifier and Type Method
      static SubSection last​(Vector<? extends HTMLNode> html, String... htmlTags)
       
      Last Match, Range Limited
      Modifier and Type Method
      static SubSection last​(Vector<? extends HTMLNode> html, int sPos, int ePos, String... htmlTags)
       
      Nth Match
      Modifier and Type Method
      static SubSection nth​(Vector<? extends HTMLNode> html, int nth, String... htmlTags)
       
      Nth Match, Range Limited
      Modifier and Type Method
      static SubSection nth​(Vector<? extends HTMLNode> html, int nth, int sPos, int ePos, String... htmlTags)
       
      Nth Match From End
      Modifier and Type Method
      static SubSection nthFromEnd​(Vector<? extends HTMLNode> html, int nth, String... htmlTags)
       
      Nth Match From End, Range Limited
      Modifier and Type Method
      static SubSection nthFromEnd​(Vector<? extends HTMLNode> html, int nth, int sPos, int ePos, String... htmlTags)

      • Methods inherited from class java.lang.Object

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