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 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 | package Torello.HTML; import java.util.Vector; import java.util.NoSuchElementException; import Torello.Java.UnreachableError; import Torello.HTML.NodeSearch.*; // Used for JavaDoc Comment Links /** * The class {@link ReplaceNodes} offers a great <B><I>efficiency-improvement</I></B> optimization * for modifying vectorized-HTML. HTML Pages can be very long, and the insertion or removal of a * piece or snippet of HMTL may result in the shifting of hundreds (or even thousands!) of * {@code HTMLNode's}. This can incur a non-trivial performance cost if many there are many * updates and changes to be made to a page. * * <BR /><BR /><HR><BR /> * * <B CLASS=JDDescLabel>Exceprt from {@link #currentNodes()}:</B> * * <BR />{@code Replaceable's} are, sort-of, <B STYLE='color: red'>the exact opposite</B> of Java's * {@code List} method {@code 'subList'}. According to the Sun / Oracle Documentation for * {@code java.util.List.subList(int fromIndex, int toIndex)}, any changes ffinamade to an instance of a * {@code 'subList'} are immediately reflected back into the original {@code List} from where they * were created. * * <BR /><BR />The {@code List.subList} operation has the advantage of being extremely easy to * work with - however, an HTML-Page {@code Vector} has the potential of being hundreds of * nodes long. Any operations that involve insertion or deletion will likely be terribly * inefficient. * * <BR /><BR /><B STYLE='color: red'><I>When the HTML inside of a {@code Replaceable} is * modified - nothing happens to the original {@code Vector} whatsoever!</I></B>. Until a user * requests that the original HTML-{@code Vector} be updated to reflect all changes that he or * she has made, the original HTML remains untouched. When an update request is finally * issued, all changes are made all at once, and at the same time! * * <BR /><BR />Again - see {@link ReplaceNodes#r(Vector, Iterable, boolean)} to understand * how quick updates on HTML-Pages is done using the {@code Replaceable} interface. * * <BR /><BR /><HR><BR /> * * <B CLASS=JDDescLabel>Utilizing class {@link ReplaceNodes}:</B> * * <BR />Class {@link ReplaceNodes} offers three methods for performing these optimized replacement * methods. These methods are listed below. The optimization that is utilized there is to first * calculate the size / length of the updated {@code Vector}, and then do the entire update all at * once. This eliminates to do any shifting and only performs a single resizing of the * {@code Vector}. * * <BR /><BR />These methods will work in lock-step with interface {@code 'Replaceable'} to * actually perform the update after all Vectorized-HTML has been changed, sufficiently as deemed * by the programmer: * * <BR /><BR /><UL CLASS=JDUL> * <LI><B>{@link ReplaceNodes#r(Vector, Iterable, boolean)}</B></LI> * <LI><B>{@link ReplaceNodes#listLI(Vector, DotPair, ObjIntConsumer)}</B></LI> * <LI><B>{@link ReplaceNodes#tableTR(Vector, DotPair, ObjIntConsumer)}</B></LI> * </UL> * * <BR /><BR />The Java Doc Upgrader Tool in this JAR Library heavily relies on using instances of * {@code Replaceable} to update and modify Java Doc HTML in a fast, simple & efficient manner. * * <BR /><BR />Though this class may look somewhat complicated to understand, in all reality it is * actually very simple. Load a web-page from disk (or download one from the Internet) and run it * through the parser (class {@link HTMLPage}) to make a Vectorized-HTML Page. Next, build a few * instances of {@link SubSection} which hold <B><I>both</I></B> the location of an HTML snippet * <B><I>and</I></B> HTML itself. * * <BR /><Br />Finallly, make whatever modifications you want to those HTML snippets, and call the * <B>{@code ReplaceNodes}</B> method listed first in the list above! The page should be updated * quickly with little cost overhead. * * <BR /><BR /><HR><BR /> * * <B CLASS=JDDescLabel>Peek Operation Replaceables</B> * * <BR />The class {@link InnerTagPeekInclusive} and {@link TagNodePeekInclusive} will always * generate properly ordered / sorted <B STYLE='color: red;'><I>references that implement the * {@code Replaceable} interface!</I></B> Furthermore, these instances will be ones that are * sorted and do not overlap. * * <BR /><BR />This means that if a set or collection of {@code Replaceable's} were created using * the {@code NodeSearch 'Peek'} Search-Classes, the * {@link ReplaceNodes#r(Vector, Iterable, boolean)} requirements that the {@code Replaceable's} be * ordered, sorted and non-overlapping would be automatically met. * * <BR /><BR />This interface is implemented by all return-values for the {@code NodeSearch} <B>Peek</B> * operations. * * <BR /><BR /><UL CLASS=JDUL> * <LI>{@link TextNodePeek}</LI> * <LI>{@link CommentNodePeek}</LI> * <LI>{@link TagNodePeek}</LI> * <LI>{@link TagNodePeekInclusive}</LI> * <LI>{@link InnerTagPeek}</LI> * <LI>{@link InnerTagPeekInclusive}</LI> * </UL> */ public interface Replaceable extends Comparable<Replaceable> { // ******************************************************************************************** // ******************************************************************************************** // basic interface stuff // ******************************************************************************************** // ******************************************************************************************** /** * Java's {@code Comparable} interface requirements. * * @return An integer based on comparing the starting locations for two {@code Replaceable} * instances. */ public default int compareTo(Replaceable other) { return this.originalLocationStart() - other.originalLocationStart(); } /** * Supplies a hash-code * * @return The value returned by {@link #originalLocationStart()}, which must be unique among * any list of {@code Replaceable's}. */ // It say this isn't allowed // public default int hashCode() // { return originalLocationStart(); } // ******************************************************************************************** // ******************************************************************************************** // The 'addAll' - used by class ReplaceNodes // ******************************************************************************************** // ******************************************************************************************** /** * Reports how many nodes were copied into {@code this} instance. * For implementing classes that inherit {@link NodeIndex}, this value will always be one. * For others, it should report exactly how many {@code HTMLNode's} were copied. * * @return Number of nodes originally contained by {@code this} instance. * * <A ID=NOTE1> <!-- NOTE --> </A> * * <BR /><BR />The purpose of {@code Replaceable's} is to allow a user to modify HTML using * a smaller sub-list, without having to operate on the entire HTML-{@code Vector} since adding * & removing nodes is one variant of {@code Vector}-modification, the <I>original-size</I> * may often differ from the <I>current-size</I>. * * <BR /><BR />When modifying HTML, if a web-page is broken into smaller-pieces, and changes * are restricted to those smaller sub-lists (and the original page is rebuilt, <I>all at * once</I>, after all changes have been made) then those modifications should require far-fewer * time-consuming list-shift operations, tremendously improving the performance of the code. */ public int originalSize(); /** * Returns how many nodes are currently in {@code this} instance. * * @return Number of nodes. See explanation of the <B STYLE='color: red;'>original</B> size, * versus the <B STYLE='color: red;'>current</B> size * <B><CODE><A HREF='#NOTE1'>here</A></CODE></B> */ public int currentSize(); /** * Returns the <B STYLE='color: red;'>start</B>-location within the original * page-{@code Vector} from whence the HTML contents of {@code this} instance were retrieved. * * <BR /><BR /><B CLASS=JDDescLabel>Start is Inclusive:</B> * * <BR />The returned value is <B STYLE='color: red;'><I>inclusive</I></B> of the actual, * original-range of {@code this} instance. This means the first {@code HTMLNode} copied into * {@code this} instance' internal data-structure was at {@code originalLocationStart()}. * * <BR /><BR /><B CLASS=JDDescLabel>Implementations of Replaceable:</B> * * <BR />The two concrete implementatons of this interface ({@link NodeIndex} and * {@link SubSection}) - both enforce the {@code 'final'} modifier on their location-fields. * (See: {@link NodeIndex#index} and {@link SubSection#location}). * * @return The {@code Vector} <B STYLE='color: red;'>start</B>-index from whence this HTML was * copied. */ public int originalLocationStart(); /** * Returns the <B STYLE='color: red;'>end</B>-location within the original * page-{@code Vector} from whence the HTML contents of {@code this} instance were retrieved. * * <BR /><BR /><B CLASS=JDDescLabel>Start is Exclusive:</B> * * <BR />The returned value is <B STYLE='color: red;'><I>exclusive</I></B> of the actual, * original-range of {@code this} instance. This means the last {@code HTMLNode} copied into * {@code this} instance' internal data-structure was at {@code originalLocationEnd() - 1} * * <BR /><BR /><B CLASS=JDDescLabel>Implementations of Replaceable:</B> * * <BR />The two concrete implementatons of this interface ({@link NodeIndex} and * {@link SubSection}) - both enforce the {@code 'final'} modifier on their location-fields. * (See: {@link NodeIndex#index} and {@link SubSection#location}). * * @return The {@code Vector} <B STYLE='color: red;'>end</B>-index from whence this HTML was * copied. */ public int originalLocationEnd(); /** * All nodes currently contained by this {@code Replaceable}. The concrete-classes which * implement {@code Replaceable} ({@link SubSection} & {@link TagNodeIndex}) allow for the * html they hold to be modified. The modification to a {@code Replaceable} happens * independently from the original HTML Page out of which it was copied. * * <BR /><BR />{@code Replaceable's} are, sort-of, <B STYLE='color: red'>the exact opposite</B> * of Java's {@code List} method {@code 'subList'}. According to the Sun / Oracle * Documentation for {@code java.util.List.subList(int fromIndex, int toIndex)}, any changes * made to an instance of a {@code 'subList'} are immediately reflected back into the original * {@code List} from where they were created. * * <BR /><BR />The {@code List.subList} operation has the advantage of being extremely easy to * work with - however, an HTML-Page {@code Vector} has the potential of being hundreds of * nodes long. Any operations that involve insertion or deletion will likely be terribly * inefficient. * * <BR /><BR /><B STYLE='color: red'><I>When the HTML inside of a {@code Replaceable} is * modified - nothing happens to the original {@code Vector} whatsoever!</I></B>. Until a user * requests that the original HTML-{@code Vector} be updated to reflect all changes that he or * she has made, the original HTML remains untouched. When an update request is finally * issued, all changes are made all at once, and at the same time! * * <BR /><BR />Again - see {@link ReplaceNodes#r(Vector, Iterable, boolean)} to understand * how quick updates on HTML-Pages is done using the {@code Replaceable} interface. * * @return An HTML-{@code Vector} of the nodes. */ public Vector<HTMLNode> currentNodes(); /** * The first node <B STYLE='color: red;'>currently</B> contained by this {@code Replaceable} * @return The First Node */ public HTMLNode firstCurrentNode(); /** * The last node <B STYLE='color: red;'>currently</B> contained by this {@code Replaceable} * @return The last node */ public HTMLNode lastCurrentNode(); // ******************************************************************************************** // ******************************************************************************************** // The 'addAll' - used by class ReplaceNodes // ******************************************************************************************** // ******************************************************************************************** /** * Add all nodes currently retained in {@code this} instance into the HTML-{@code Vector} * parameter {@code html}. The nodes are appended to the end of {@code 'html'}. Implementing * classes {@link NodeIndex} and {@link SubSection} simply use the Java {@code Vector} method's * {@code add} (for {@code NodeIndex}) and {@code addAll} (for {@code SubSection}). * * @param html The HTML-{@code Vector} into which the nodes will be appended (to the end of * this {@code Vector}, using {@code Vector} methods {@code add} or {@code addAll} dependent * upon whether one or more-than-one nodes are being inserted). * * @return The result of {@code Vector} method {@code add}, or method {@code allAll} */ public boolean addAllInto(Vector<HTMLNode> html); /** * Add all nodes currently retained in {@code this} instance into the HTML-{@code Vector} * parameter {@code html}. * * @param index The {@code 'html'} parameter's {@code Vector}-index where these nodes are to * be inserted * * @param html The HTML-{@code Vector} into which the nodes will be appended (to the end of * this {@code Vector}, using {@code Vector} methods {@code add} or {@code addAll} dependent * upon whether one or more-than-one nodes are being inserted). * * @return The result of {@code Vector} method {@code add}, or method {@code allAll} */ public boolean addAllInto(int index, Vector<HTMLNode> html); // ******************************************************************************************** // ******************************************************************************************** // update - inefficient, unless only used for a single page-update // ******************************************************************************************** // ******************************************************************************************** /** * <EMBED CLASS='external-html' DATA-FILE-ID=REPL_UPDATE_DESC> * * @param originalHTML The original page-{@code Vector} where the nodes in {@code this} * instance were retrieved * * @return The change in the size of the {@code Vector} * * @see ReplaceNodes#r(Vector, Iterable, boolean) * * @throws IndexOutOfBoundsException If {@link #originalLocationStart()} or * {@link #originalLocationEnd()} are not within the bounds of the input html-page. */ public int update(Vector<HTMLNode> originalHTML); // ******************************************************************************************** // ******************************************************************************************** // Building New Instance: Change the HTML of a Replaceable, **WITHOUT USING SUB-CLASS' FIELDS** // ******************************************************************************************** // ******************************************************************************************** /** * This method may be used for arbitrary replacements. An instance of {@code NodeIndex} * (one of its sub-classes) only contains a single {@code HTMLNode}. To change that to a list, * or to remove that node altogether, invoke this method, and a new instance of * {@code Replaceable} will be automatically created, and returned. * * <BR /><BR />This may be a little tricky at first, but the primary reason for using this * method is that size-changes that would make a <B STYLE='color: red;'>single-node</B> * ({@link NodeIndex} instance) into a <B STYLE='color: red;'>list</B> ({@link SubSection} * instance), or vice-versa, would require building a different type of {@code Replaceable} * instance. This method will automatically build that instance into a {@code Replaceable} * that retains its <I>original location</I>, but reflects its <I>new contents and size</I>. * * <BR /><BR />Once again, the primary impetus for this method is using it with an in-place * page update having multiple-replacements, <I>vis-a-vis</I> a call to * {@link ReplaceNodes#r(Vector, Iterable, boolean)}. * * @param newHTML The contents of {@code 'this'} replaceable will be assigned to the the html * in this parameter. * * @return a new replaceable whose <I><B STYLE='color: red;'>location</B> has not changed</I>, * but whose contents are the contents of {@code newHTML}. */ public default Replaceable setHTML(Vector<HTMLNode> newHTML) { final int oldSize = this.originalSize(); final int newSize = newHTML.size(); final int sPos = this.originalLocationStart(); final int ePos = this.originalLocationEnd(); // SubSection ==> SubSection if ((oldSize > 1) && (newSize > 1)) return new SubSection(new DotPair(sPos, ePos - 1), newHTML); // NodeIndex ==> NodeIndex if ((oldSize == 1) && (newSize == 1)) return NodeIndex.newNodeIndex(sPos, newHTML.elementAt(0)); // Empty ==> Empty if ((oldSize == 0) && (newSize == 0)) return empty(sPos); return new ReplaceableAdapter(sPos, ePos, newHTML); } /** * See the description in {@link #setHTML(Vector)} to understand when to use {@code setHTML}. * This method is identical, but accepts a single {@link HTMLNode} instance, instead of an html * list. * * @param newHTML The contents of {@code 'this'} replaceable will be assigned to the the html * contained by {@code newHTML}. (The returned instance will have the same location values) * * @return a new replaceable whose <I><B STYLE='color: red;'>location</B> has not changed</I>, * but whose contents are {@code newHTML}. * * @see #setHTML(Vector) */ public default Replaceable setHTML(HTMLNode newHTML) { // NodeIndex ==> NodeIndex if (this.originalSize() == 1) return NodeIndex.newNodeIndex(this.originalLocationStart(), newHTML); Vector<HTMLNode> v = new Vector<>(); v.add(newHTML); return new ReplaceableAdapter (this.originalLocationStart(), this.originalLocationEnd(), v); } /** * Removes all HTML from this {@code Replaceable}, such that's {@link #currentNodes()} would * return an empty HTML list. * * @return a new replaceable whose original <I><B STYLE='color: red;'>location</B> has not * changed</I>, but whose contents are empty. * * @see #setHTML(Vector) */ public default Replaceable clearHTML() { if (currentSize() == 0) return Replaceable.empty(originalLocationStart()); return new ReplaceableAdapter (originalLocationStart(), originalLocationEnd(), new Vector<>()); } // ******************************************************************************************** // ******************************************************************************************** // Creating Replacebles, using the Adapter, avoiding the Concrete-Class' exception checks. // ******************************************************************************************** // ******************************************************************************************** /** * Provides a mechanism for creating a {@link SubSection} instance whose {@code html} does not * match the size of the {@code location} where that {@code html} is to be placed. * * @param location The range in any HTML Page by which the new {@code html} will be replaced. * * @param html The html that will ultimately be used to replace the current-html, <I>on a * web-page, at the specified {@code location}</I>. * * @return An instance of a {@code Replaceable}, that is, in-effect, a {@link SubSection}, but * one whose location/bounds do not match the size of the new-{@code html}. * * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> This method allows a user to bypass the * exception-check that class {@code SubSection} performs when building an instance of that * class. */ public static Replaceable create(DotPair location, Vector<HTMLNode> html) { return new ReplaceableAdapter(location.start, location.end + 1, html); } /** * Creates a new {@code Replaceable} instance whose original-location is just a single-node, * but whose new {@code html} may be an arbitrarily-sized html {@code Vector}. * * @param location The node in any HTML Page which shall be replaced by {@code 'html'} * * @param html The html that will replace the node on an HTML page located at * {@code 'location'} * * @return An instance of a {@code Replaceable} that is, in effect, a {@link SubSection}, * but one whose location/bounds are not (necessarily) a single page-index. * * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> This method allows a user to bypass the * requirement that a {@code NodeIndex} occupy only a single-node. */ public static Replaceable create(int location, Vector<HTMLNode> html) { return new ReplaceableAdapter(location, location + 1, html); } /** * Creates a new {@code Replaceable} instance whose original-location had zero-length * * @param location The location in any HTML Page into which the {@code 'html'} shall be * inserted * * @param html The html that will be inserted into an HTML Page at index {@code 'location'} * * @return An instance of a {@code Replaceable} - whose original-location had a zero-length */ public static Replaceable createInsertion(int location, Vector<HTMLNode> html) { return new ReplaceableAdapter(location, location, html); } // ******************************************************************************************** // ******************************************************************************************** // After updating an HTML-Page, this will incorporate the changed size & location // ******************************************************************************************** // ******************************************************************************************** /** * This method is mostly of internal-use, mainly by * {@link ReplaceNodes#r(Vector, Iterable, boolean)} * * @param sPos The new location in an html page-{@code Vector} where the contents of this * {@code Replaceable} are now located. * * @return A new instance, whose html-contents are identical, but is located at {@code 'sPos'} * (and having an ending-location of {@code sPos + currentSize()}). */ public default Replaceable moveAndUpdate(int sPos) { // IMPORTANT: This method is extremely un-important! It looks kind of unreadable. // All it is doing is REGISTERING the changes to his SubSection or NodeIndex // by building a new SubSection or new NodeIndex. // // PRIMARILY: Since the *WHOLE POINT* is to make all of the changes to an HTML Page, first, // before doing an update ... Having updated Replaceable's is mostly a waste. // Specifically, after the page has been updated, keeping the sub-parts of the // page would no longer be necessary! // // ReplaceNodes: This class offers the option to 'updateReplaceablesAfterBuild' in case // (for whatever reason) the user has decided another round of page updates is // needed. final int size = currentSize(); switch (size) { case 0: return Replaceable.empty(sPos); case 1: return NodeIndex.newNodeIndex(sPos, firstCurrentNode()); default: return new SubSection( // DotPair.end is inclusive, so subtract 1 new DotPair(sPos, sPos + size - 1), // The current HTML Vector currentNodes() ); } } // ******************************************************************************************** // ******************************************************************************************** // Creating an Empty Replaceable // ******************************************************************************************** // ******************************************************************************************** /** * Returns an empty {@code Replaceable} (an instance having 0 {@code HTMLNode's}) located at * {@code sPos}. * * <BR /><BR /><B CLASS=JDDescLabel>NoSuchElementException:</B> * * <BR />Attempting to retrieve nodes from the returned-instance will generate a * Java {@code NoSuchElementException}. * * @param sPos The location of this zero-element {@code Replaceable} * @return The new instance. */ public static Replaceable empty(final int sPos) { return new ReplaceableAdapter(sPos, sPos, new Vector<>()); } // ******************************************************************************************** // ******************************************************************************************** // Synthetic // ******************************************************************************************** // ******************************************************************************************** /** * Identifies whether or not {@code 'this'} instance is an anonymous class, that was built from * the (internal) {@code ReplaceableAdapter}. * * @return {@code TRUE} if {@code 'this'} is <B STYLE='color: red;'>neither</B> an instance * that inherits {@code NodeIndex} <B STYLE='color: red;'>nor</B> inherits {@link SubSection}. * Such instances are built from an internal {@code ReplaceableAdapter}, and are produced by * the methods: {@link #setHTML(Vector)}, {@link #setHTML(HTMLNode)}, {@link #clearHTML()}, * and {@link #empty(int)}. */ public default boolean isSynthetic() { return false; } } |