Package Torello.HTML

Class ReplaceNodes


  • public class ReplaceNodes
    extends java.lang.Object
    ReplaceNodes - Documentation.

    Generally, this class is reasonably similar to the class Attributes in that it can be used to quickly replace certain elements in a vectorized-html web-page. Here, though, rather than using the pre-defined methods from the enumerated-type enum AUM, a programmer is expected to write a java.util.function "Lambda Functional Interface." This interface has a pre-defined interface in this sub-package - interface ReplaceFunction.

    When using the AUM and Attributes class pair to update vectorized web-page elements, there is a limited subset of actions that can be performed on the nodes. The class ReplaceNodes and ReplaceFunction is much lighter and allows a programmer to change any feature about a TagNode, or any node by writing an appropriate lambda.



    • Method Detail

      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             int[] posArr,
                             ReplaceFunction rf)
        This short function will iterate a loop over the integer-pointer values in int[] posArr, and replace every position in the underlying Vector<HTMLNode> with a new node supplied by the interface ReplaceFunction. It should be obvious, lambda may be used here, but is not necessary - any implementing interface may be used for parameter 'rf'

        NOTE: If the value returned by the replace-lambda function's 'getReplacement(...)' method is null, null will indeed be inserted into that Vector position.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        posArr - This is usually generated by one of the node-search 'Find.all(...)' methods. Each and every one of the 'Find.all(...)' methods in the search package will return an array of integers. These integers represent positions/locations in the passed HTML page Vector.
        rf - This is just a class that implements the interface ReplaceFunction. The interface has a single-method that will receive the position in the Vector, along with the HTMLNode found at that location. It is expected to produce a new version of the HTMLNode. This new node will be substituted into the HTML page or subsection.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - IMPORTANT NOTE: Usually, a position-array is generated by one of the search-methods in the NodeSearch package. If, however, the Vector has since changed and posArr contains stale-data, or if for other reasons there are invalid index-pointers in posArr, then an ArrayIndexOutOfBoundsException will, naturally, be thrown by java's Vector.setElementAt(...) method.
        See Also:
        ReplaceFunction
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
         int counter=0;
         for (int pos : posArr)
             html.setElementAt(
                 // pos is the vector-position, counter is the "iteration-count"
                 rf.getReplacement(html.elementAt(pos), pos, counter++),
                 pos
             );
        
      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             int[] posArr,
                             HTMLNode n)
        This will replace every node indicated by 'posArr' with the same replacement node - parameter 'n'.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        posArr - This is usually generated by one of the node-search 'Find.all(...)' methods. Each and every one of the 'Find.all(...)' methods in the search package will return an array of integers. These integers represent positions/locations in the passed HTML page Vector.
        n - This may be any non-null HTMLNode. This node shall be inserted (and will replace) each node indicated by the parameter 'posArr'.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - IMPORTANT NOTE: Usually, a position-array is generated by one of the search-methods in the NodeSearch package. If, however, the Vector has since changed and posArr contains stale-data, or if for other reasons there are invalid index-pointers in posArr, then an ArrayIndexOutOfBoundsException will, naturally, be thrown by java's Vector.setElementAt(...) method.
        Code:
        Exact Method Body:
        1
        2
         int len= html.size();
         for (int i=0; i < len; i++) html.setElementAt(n, i);
        
      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             ReplaceFunction rf)
        This short function will iterate a loop over the entire html-page, checking every node. The replace function is expected to either:

        • provide a replacement HTMLNode for the indicated position
        • return null as a value - in which case, no substitution will occur

        It might (hopefully) be be obvious that a lambda may be used here. And, also, it is not mandatory, nor required - any implementation of the Java Functional-Interface will suffice.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        rf - This is just a class that implements the interface ReplaceFunction. The interface has a single-method (@code getReplacement(...)} that will receive the position in the Vector, along with the HTMLNode found at that location. It is expected to return a new version of the HTMLNode - or return null if it is decided no replacement / substitution is needed.
        See Also:
        ReplaceFunction, HTMLNode
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
         int size = html.size();
         for (int pos=0; pos < size; pos++)
         {
             // Here the vector-position and iteration-number are the same
             HTMLNode n = rf.getReplacement(html.elementAt(pos), pos, pos);
             if (n != null) html.setElementAt(n, pos);
         }
        
      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             int[] posArr,
                             java.util.Vector<HTMLNode> newNodes)
        This short function will iterate a loop over the integer-pointer values in int[] posArr, and replace every position in the underlying Vector<HTMLNode> with a from the Vector<> newNodes parameter.
        Parameters:
        html - Any HTML page or section that has been loaded already.
        posArr - This is usually generated by one of the node-search 'Find.all(...)' methods. Each and every one of the 'Find.all(...)' methods in the search package will return an int[] array. These integers represent positions/locations in the passed HTML page Vector.
        newNodes - This list of new nodes must have a length identical to the int[] posArr (pointer-Array) length.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - This exception will throw if any of the elements of 'posArr' point to a position in the Vector<HTMLNode> v parameter that are out of bounds for that Vector.
        java.lang.IllegalArgumentException - if the length of the position array (pointer-array) is not identical to the length of the new-nodes Vector.
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
        8
         if (posArr.length != newNodes.size()) throw new ArrayIndexOutOfBoundsException(
             "The pointer array 'posArr', and the replacement-node array 'newNodes' do not have " +
             "equal lengths!\n" +
             "posArr.length=" + posArr.length + ", newNodes.size()=" + newNodes.size()
         );
        
         int newNodesPos = 0;
         for (int pos : posArr) html.setElementAt(newNodes.elementAt(newNodesPos++), pos);
        
      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             DotPair replaceRange,
                             java.util.Vector<HTMLNode> newNodes)
        Replaces the nodes currently within the vectorized HTML parameter 'html', in the sub-range provided by the 'replaceRange' parameter, with the new nodes provided by the 'newNodes' parameter. This is, essentially, a sub-range array-copy operation.

        Unless exactly the same number of nodes that are in the 'replaceRange' are also in 'newNodes', this method shall have to shorten or lengthen the size of the HTML Vector.
        Parameters:
        html - This may be any HTML page or sub-page
        replaceRange - This is the range of HTMLNode's that are going to be removed. After removal, new nodes (from parameter 'newNodes'), will be inserted into the same location in the HTML Vector where the previous nodes had resided.
        newNodes - These are the new HTMLNode's that are to replace the old ones.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - This exception will throw if the specified range is not within the bounds of the Vector
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
         if (replaceRange.end >= html.size()) throw new ArrayIndexOutOfBoundsException(
             "The instance of DotPair provided " + replaceRange.toString() + ", indicates a " +
             "range that is past the length of the html Vector<HTMLNode>, which has size: " +
             "[" + html.size() + ']'
         );
        
         // Replacement while-loop.  This will replace all nodes that can be replaced in the
         // "replace range" - without growing or shrinking the size of the underlying vector.
         // AFTERWARDS   If there are still more nodes to insert, they will be inserted by
         //              growing the vector.
         // AND ALSO     If there were fewer nodes to insert than the number that need to be
         //              removed the Vector will be shortened.
        
         int i = 0;
         int j = replaceRange.start;
        
         while ((j <= replaceRange.end) && (i < newNodes.size()))
         {
             html.setElementAt(newNodes.elementAt(i), j);
             i++; j++;
         }
        
         // CASE 1: The number of nodes to be removed is precisely equal to the number of nodes
         //         that are being re-inserted.
         if (replaceRange.size() == newNodes.size()) return;
        
         // CASE 2: More nodes were removed that the number of nodes to be inserted.  In this case
         //         the original HTML Vector will SHRINK in SIZE.  Make use of Util.removeRange(...)
         //         to get ride of the remaining nodes that were not replaced.
         if (j <= replaceRange.end)
         {
             Util.removeRange(html, j, replaceRange.end + 1);    // +1 is needed here,
             return;                                             // sPos/ePos ... ePos is EXCLUSIVE
         }
        
         // CASE 3: The HTML Vector is going to grow.  There were fewer nodes removed than the
         //         number of nodes to be inserted.  Utilize Vector.addAll(...) to add the rest
         //         of the nodes that were not inserted in the for-loop at the top.
         Vector<HTMLNode> temp = new Vector<>(newNodes.size() - i);
        
         while (i < newNodes.size()) temp.add(newNodes.elementAt(i++));
        
         html.addAll(replaceRange.end + 1, temp);
        
      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             DotPair replaceRange,
                             HTMLNode newNode)
        Replaces the nodes currently within the vectorized HTML parameter 'html', in the sub-range provided by the 'replaceRange' parameter, with a single new node provided by the 'newNode' parameter. Essentially, this is a 'Range Removal' Operation, because a complete sublist is removed, as only a single-node replaces it.

        Unless 'replaceRange' has size equal to '1', this operation will shorten the size of the input HTML Vector by replaceRange.size() - 1 nodes.
        Parameters:
        html - This may be any HTML page or sub-page
        replaceRange - This is the range of HTMLNode's that are going to be removed. After removal, parameter 'newNode', will be inserted into the same location in the HTML Vector where the previous nodes had resided.
        newNode - This is the new HTMLNode that is to replace the (entire) list specified by DotPair parameter 'replaceRange'.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - This exception will throw if the specified range is not within the bounds of the Vector
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         if (replaceRange.end >= html.size()) throw new ArrayIndexOutOfBoundsException(
             "The instance of DotPair provided " + replaceRange.toString() + ", indicates a " +
             "range that is past the length of the html Vector<HTMLNode>, which has size: " +
             "[" + html.size() + ']'
         );
        
         html.setElementAt(newNode, replaceRange.start);
        
         if (replaceRange.size() > 1)
             Util.removeRange(html, replaceRange.start + 1, replaceRange.end + 1);
        
      • r

        public static void r​(java.util.Vector<HTMLNode> html,
                             int replacePos,
                             java.util.Vector<HTMLNode> newNodes)
        Replaces the instance of HTMLNode located at Vector-index 'pos' with the contents of of Vector parameter 'newNodes'. This removes just a single instance of HTMLNode, and replaces it with a list of nodes.

        Note that this method will, indeed, lengthen the size of the input HTML Vector (unless the 'newNodes' Vector being inserted has only 1 or 0 elements).
        Parameters:
        html - This may be any HTML page or sub-page.
        replacePos - The position of the HTMLNode to be removed and replaced with the list of nodes.
        newNodes - These are the new HTMLNode's that are to replace the old instance of HTMLNode at position 'pos'..
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - This exception will throw if the specified 'pos' parameter is not within the bounds of the Vector.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
         if (replacePos < 0) throw new ArrayIndexOutOfBoundsException(
             "The position passed to this method [" + replacePos + "] is negative."
         );
        
         if (replacePos >= newNodes.size()) throw new ArrayIndexOutOfBoundsException(
             "The position passed to this method [" + replacePos + "] is greater than or equal " +
             " to the size of the input HTML Vector parameter, 'html' [" + html.size() + "]"
         );
        
         html.removeElementAt(replacePos);
         html.addAll(replacePos, newNodes);