Package Torello.HTML

Class Replacement

java.lang.Object

Torello.HTML.Replacement

public class Replacement
extends java.lang.Object

The means by which the Replaceable interface may be used to efficiently update a modified HTML-Vector, quickly, and all-at-once.

This class has but two public methods. The both accept a single Java-Vector, and either a single Replaceable, or a list of Replaceable's. These Replaceable's must have been 'derived' from that self-same input Vector.

The class will iterate those User-Provided Replaceable's, modifying the contents of the original / input Vector to reflect those changes.

Efficient-Transformations
The sole benefit of the Replaceable-interface is such that it allows a programmer to avoid large numbers of array-shift and array-copy operations.

If a user decides to modify the contents of an HTML-Table, for instance, he should first copy the HTMLNode-Contents of that table out of an input-Vector and into a Java-HTML SubSection instance. Afterwards, the HTMLNode-Content of that SubSection may be modified in any way that the user sees fit.

SubSection's of HTML have vastly smaller amounts of nodes inside their internal-array's (the Java-Package 'java.util.*' data-structures have array's among their private data-fields). Because the amount of nodes in an HTML-SubSection will always be fewer, the number of node-shifts that are required to modify that HTML will, obviously, always be tremendously fewer too.

By using the Replaceable-interface classes, a user may hold off the innefficent transformation of a Vectorized-HTML until all changes have been decided, at which point, they may be progpogated back into the original HTML-Vector, in a single pass (using this class' sole-method) -thereby avoiding large number of array-copy and shift operations!

See Also:

SubSection, NodeIndex

Hi-Lited Source-Code:

• View Here: Torello/HTML/Replacement.java
• Open New Browser-Tab: Torello/HTML/Replacement.java

File Size: 17,464 Bytes Line Count: 352 '\n' Characters Found

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
• 1 Method(s), 1 declared static
• 0 Field(s)

Method Summary

Replace HTMLNode's inside HTML-Vector with nodes obtained from Vector of Replaceables
Modifier and Type	Method
static Ret2<Vector<HTMLNode>, Vector<Replaceable>>	run(Vector<HTMLNode> page, Iterable<? extends Replaceable> updatedReplaceables, boolean updateReplaceablesAfterBuild)

Methods inherited from class java.lang.Object

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

Method Detail

run

⇈ ⮫ 🗕 🗗 🗖

public static Ret2<java.util.Vector<HTMLNode>,java.util.Vector<Replaceable>> run
            (java.util.Vector<HTMLNode> page,
             java.lang.Iterable<? extends Replaceable> updatedReplaceables,
             boolean updateReplaceablesAfterBuild)

Updates a page Vector using a list of Replaceable 's that have been retrieved & copied from that Vector. The intention here is that if-and-when the contents of the Replaceable's currentNodes() have been modified, those updates and changes need to be reflected / propogated back into the original HTML-Vector eventually.

To see a use of this method from the Java Doc Upgrader Package, click on the HiLited Source-File Below. This source-code example inserts a third-table column into an HTML Table for the page Package Summary page of the package Torello.Java.Function. Adding additional Table Columns to an already existing HTML-Table is done very efficiently, even without a DOM Tree (using Vectoried-HTML instead) via the 'Peek-Inclusive' search methods and this replace-function.

FunctionPackageSummary.java

Parameters:

page - Any HTML page (or sub-page), but this parameter must contain the HTML from whence the contents of the 'updatedReplaceables' iterable was created (usually by a Node Search 'Peek' methods).

IMPORTANT NOTE: 'page' should not have been modified at all since the extraction of the SubSection and NodeIndex elements contained by updatedReplaceables. The entire purpose of a Replaceable is to modify / update / "change" the contents of the Replaceable's themselves, rather than modifying the underlying page-Vector!. Remember, because the HTML in this package is saved as a List, rather than a DOM Tree, any time an HTMLNode is inserted or deleted, the entire page will need to be shifted by that many nodes because of the upsert (insert or delete).

NOTE: If the page has been resized in anyway, what-so-ever, the loops in this method will be replacing the wrong nodes, and the returned Vector will be entirely incorrect.

Using a "Peek" method (which returns Replaceable instances) and changing the sub-parts of that page individually (and afterwards rebuilding the page using this method), insert and delete operations can be made an order of magnitude more efficient.

updatedReplaceables - This should be a sorted collection of HTML Replaceable instances. Replaceable's are easily be obtained using one of the Node Search Peek methods. For instance, calling TagNodePeekL1Inclusive, and requesting all HTML <LI> elements would return a Vector<Replaceable> having all of the list <LI> items found inside of an HTML <OL> or <UL> list.

Parameter Requirements:

• The Replaceable elements must be sorted, by their Replaceable.originalLocationStart(), fields, from first to last.
• The Replaceable locations may not overlap each other.
• Each Replaceable.originalLocationStart() AND Replaceable.originalLocationEnd() must be within the range of (they must 'fit' into) 'page'. Specifically, the integers returned by these methods must be less than or equal to page.size()

NOTE: These requirements are all mostly obeyed automatically if the Inclusive-Peek operations from the NodeSearch package were invoked to generate the Vector<Replaceable> passed to 'updatedReplaceables'. The word 'mostly' is used here because of the second requirement stating that these sections may not overlap. Peek operations may return overlapping HTML segments, when searching, for instance for multiple tag. Care should be taken when modifying HTML by looking for the relevant parts that are needed.

AGAIN: For each Replaceable, it's Replaceable.originalLocationStart() and Replaceable.originalLocationEnd() fields will not have been changed, while the Replaceable.currentHTML() is what should have been changed (if changes are to be made to a given section). This, indeed, means that when this method is invoked, the length / size of the 'html' field will not necessarily be consistent with the length / size of its corresponding 'location' field.

updateReplaceablesAfterBuild - When the updated sections are pieced together, and placed into the return-Vector, they will have different locations in that newly returned HTML 'page'. When TRUE is passed to this parameter, the 'updatedReplaceables' iterable-list will havve Replaceable's with stale-location fields. For class SubSection, it's location field will be stale, and for the NodeIndex classes, their index fields will no longer relfect their node's actual location in the newly constructed HTML page.

NOTE: This should not cause any concert, unless a further round of modifications need to be made to the page.

1. When TRUE is passed to this parameter, a list of newly constructed Replaceable instances will be built using the same html, and updated location values (and that list will be placed into the field Ret2.b).
   
   
2. When this parameter receives FALSE, the returned Ret2.b Field will be null.

Returns:

IMPORTANT! Unlike many of the list-modification methods in Java HTML, this is not an in-place replacement! The Vector that is returned by this method will be the updated Vector, while the Vector-parameter passed ('page') shall remain unchanged.

NOTE: The whole basis of 'the optimization' going on here is that the Vector is only resized once! Performing an in-place substitution would result in Vector-elements constantly being shifted, and the Vector, itself, being resized.

Ret2<Vector, Vector>:

• Vector<HTMLNode> - Ret2.a
  
  The updated / modified html page. The original-input Vectorized HTML will remain unchanged!
  
  
• Vector<Replaceable> - Ret2.b
  
  The Replaceable's themselves can be updated if the user has passed TRUE to parameter updateReplaceablesAfterBuild. If FALSE was passed to the parameter, then the field Ret2.b will be null.
  
  Note that this should seldom be necessary. If for whatever reason another round of changes will need to be made to the page, then and only then should TRUE be passed to updateReplaceablesAfterBuild.
  
  The update that is performed on the input-Replaceable's is done to adjust their locations to reflect their new locations within the newly built html-page.
  
  This is done by creating new Replaceables with the same html, but different locations, and putting them in the returned Vector, which can be retrieve via Ret2.b

Throws:

ReplaceableOutOfBoundsException - If any of the Replaceable instances returned by the 'updatedReplaceables' iterator-parameter have original location Vector-indices that are not within the bounds of the HTML page-Vector (parameter 'page').

ReplaceablesOverlappingException - If any of the Replaceable instances returned by the 'updatedReplaceables' iterator-parameter have original location Vector-indices that overlap.

ReplaceablesUnsortedException - If any of the Replaceable instances returned by the 'updatedReplaceables' iterator-parameter have original-starting locations that are non-consecutive (out of order!)

Code:

Exact Method Body:

 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // First check for the case that 'updatedReplaceables' is empty
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 final int SIZE = page.size();

 // This entire loop is merely done for nothing more than error/exception checking.
 // It is mandatory that the SubSections which are passed are all 'in-order', that
 // none of them overlap, and that they all fit inside the 'page' vector parameter.

 Iterator<? extends Replaceable> iter = updatedReplaceables.iterator();

 // If there are no Replaceables in the Iterable, return the original page.
 if (! iter.hasNext())
 {
     if (! updateReplaceablesAfterBuild) return new Ret2<>(page, null);

     Vector<Replaceable> ret = new Vector<>();
     for (Replaceable r : updatedReplaceables) ret.add(r);
     return new Ret2<>(page, ret);
 }


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Initialize the Loop variables
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 Replaceable replaceable         = iter.next();
 Replaceable previousReplaceable = null;

 // These are used, specifically, for the error-checking part of the loop
 int start1  = replaceable.originalLocationStart();
 int end1    = replaceable.originalLocationEnd() - 1;  // Value is Exclusive
 int start2  = -1;
 int end2    = -1;

 // This is used for the exception messages only.  It is incremented on the last line of the
 // loop body.

 int i=0;

 // These are used, specifically, for the part that computes the size the final vector
 int size = 0;   // Total (Future) Size of the Return / Output Vector
 int last = 0;   // Temp Variable, it is easier to have a separate one for this

 while (iter.hasNext())
 {
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Compute what the size of the returned HTML-Vector is going to be.
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     //
     // This is done by looking at the locations of all the replacements, and the number of
     // nodes between each replacement.
     //
     // For the part of this loop that is computing the size of the final vector, there
     // start2 and end2 pointers should just be ignored.  The start1, end1 pointer pair
     // are sufficient, as during each iteration, start2 and end2 are assigned to start1 and
     // end1 in the very next step anyways.
    
     size += (start1 - last);            // Size of the previous "in-between chunk"
     size += replaceable.currentSize();  // Size of the next SubSection
     last = end1;                        // advance the 'last' pointer

        
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Advance the Validity-Checking Pointer Pairs
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     // Advance pointer-pair #1 (but DONT'T do this one the VERY FIRST ITERATION)
     if (i > 0)
     {
         start1  = start2;
         end1    = end2;
     }

     // Advance Pointer Pair #2
     previousReplaceable = replaceable;
     replaceable         = iter.next();
     start2              = replaceable.originalLocationStart();
     end2                = replaceable.originalLocationEnd() - 1;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // NOW... THE VALIDITY-CHECKING IF-STATEMENTS
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     /*
     System.out.println(
         "previousReplaceable: " + previousReplaceable +
         ", replaceable: " + replaceable + '\n' +
         "start1: " + start1 + ", end1: " + end1 + ", start2: " + start2 + ", end2: " + end2
     );
     */

     if (start2 < start1)

         throw new ReplaceablesUnsortedException(
             "'updatedReplaceables' contains at least one Replaceable Element-Pair " +
             "which is not sorted from first to last:\n" +
             "The " + (i+1) + StringParse.ordinalIndicator(i+1) + " Replaceable returned " +
             "by 'updatedReplaceables' starts at page-index " + start1 + '\n' +
             "The " + (i+2) + StringParse.ordinalIndicator(i+2) + " Replaceable returned " +
             "by 'updatedReplaceables' starts at page-index " + start2,
             previousReplaceable, replaceable
         );


     if (    (start2 == start1)  // New section starts at same place as the previous section
         ||  (start2 <= end1)    // New section begins before the previous section ended
    
         // !!! Whenever a user has created a zero-length-replaceable (zero original length)
         // then the "end" of that replaceable will be "start-1".  Sounds a little silly,
         // right?  Well inserting a zero-length replaceable happens a lot in JavaDoc
         // Upgrader.  The two cases of the if-statement are both important.  Remember, the
         // iterator must be returning sorted elements, or else the previous if statement
         // would have already failed.
         )

         throw new ReplaceablesOverlappingException(
             "'updatedReplaceables' contains at least one Replaceable Element-Pair " +
             "that overlap each-other:\n" +
             "The " + (i+1) + StringParse.ordinalIndicator(i+1) + " Replaceable returned " +
             "by 'updatedReplaceables' has original-location " +
             "[" + start1 + ", " + end1 + "]\n" +
             "The " + (i+2) + StringParse.ordinalIndicator(i+2) + " Replaceable returned " +
             "by 'updatedReplaceables' has original-location " +
             "[" + start2 + ", " + end2 + ']',
             previousReplaceable, replaceable
         );

     if (end1 > SIZE)

         throw new ReplaceableOutOfBoundsException(
             "There was a Replaceable Element whose original-location was not within the " +
             "bounds of page:\n" +
             "The " + (i+1) + StringParse.ordinalIndicator(i+1) + " Replaceable returned " +
             "by 'updatedReplaceables' has original-location " +
             "[" + start1 + ", " + end1 + "]\n" +
             "While page.size() is: " + SIZE,
             replaceable
         );

     i++;
 }


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // POST-LOOP FINISHING TOUCHES
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 // "Ending Read" Check.  The very last location is not checked, because the loop breaks
 // before it gets to check pointer-pair-2 (on the last iteration)
 //
 // NOTE: The patholigical-cae where there is **ONLY ONE** SubSection in the updatedReplaceables
 //       input Collection.  If pointer-pair-2 is -1, there is no need to check it... :)
 //       If (pointer-pair-2 == -1), the loop body was never entered

 if (end2 != -1) if (end2 >= SIZE)

     throw new ReplaceableOutOfBoundsException(
         "There was a Replaceable Element whose original-location was not within the " +
         "bounds of page:\n" +
         "The " + (i+2) + StringParse.ordinalIndicator(i+2) + " Replaceable returned by " +
         "'updatedReplaceables' has original-location [" + start2 + ", " + end2 + "]\n" +
         "While page.size() is: " + SIZE,
         replaceable
     );

 // the very-last replaceable was not added to the size.
 size += (start1 - last);            // Size of the previous "in-between chunk"
 size += replaceable.currentSize();  // Size of the next SubSection
 last = end1;


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Build the Return Vector - NOTE - We just computed its final size!
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 //
 // ALSO: If the user has requested the DP's be udated, also build the "newSubSections" Vec
 //
 // The purpose of the above computation was for instantiating a properly-sized vector
 // at construction time.  This will save quite a bit of time that would be wasted on
 // vector resizing.

 Vector<HTMLNode> ret = new Vector<>(size);


 // By user request, only!  This really isn't *THAT* important.  All that the
 // 'newSubSections' Vector will have shall be the exact same-subsections that are passed
 // as a parameter to this method through the 'updatedReplaceables' parameter - *EXCEPT* that
 // their SubSection.location fields will be updated to hold the *ACTUAL* / *NEW* locations

 Vector<Replaceable> newReplaceables =
     updateReplaceablesAfterBuild ? new Vector<>() : null;


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // MAIN-LOOP: Iterate each of the Replaceables that was passed as input to this method.
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 //
 // Add their contents to Output-Vector, and make sure to add all "in-between" nodes too!

 // The index-pointer to the **ORIGINAL-VECTOR** (a.k.a. the input vector)
 int pagePos=0;


 // This loop does the replacement.  It is quick and easy if you understand what replacing
 // a list of subsections involves.

 for (Replaceable r : updatedReplaceables)
 {
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
     // Add all of the MOST-RECENT "In-Between Nodes"  (These are all nodes before next SS)
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     //
     // AFTERWARDS: Add all nodes in the next Sub-Section 

     // Retrieve all of the 'in-between' nodes
     while (pagePos < r.originalLocationStart()) ret.add(page.elementAt(pagePos++));

     // Add this Replaceable to the returned output list!
     r.addAllInto(ret);

     // Skip over the old nodes.
     pagePos = r.originalLocationEnd(); // don't add one, value is exclusive


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 
     // User may request that the Sub-Section 'Locations' be updated, rather than discarded
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 

     // This is done for convenience so that the user knows where the sections are all
     // located in the new build.
     //
     // NOTE: All this is doing is changing the 'location' field of the old subsection
     //       which has changed to contain the new 'location'

     if (updateReplaceablesAfterBuild)
     {
         int ePos = ret.size();
         int sPos = ePos - r.currentSize() + 1;

         newReplaceables.add(r.moveAndUpdate(sPos));
     }
 }


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // IMPORTANT: Add the last / final Elements that occur *AFTER* the *LAST* Sub-Section
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 //
 // This part should also be called "The Tail" of the Page.  (Put the Page-Tail back)

 while (pagePos < page.size()) ret.add(page.elementAt(pagePos++));


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // AGAIN: User may request that Sub-Section 'Locations' be updated, rather than discarded
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 return updateReplaceablesAfterBuild
     ? new Ret2<>(ret, newReplaceables)
     : new Ret2<>(ret, null);