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
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
package Torello.HTML.Tools.NewsSite;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;
import Torello.Java.*;

import Torello.Java.Additional.Ret4;

import static Torello.Java.C.*;

import java.util.*;
import java.io.*;

import java.net.URL;
import java.util.concurrent.TimeUnit;

/**
 * This class runs the primary iteration-loop for downloading news-articles using a list of
 * article-{@code URL's}.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=SCRAPE_ARTICLES>
 */
@Torello.JavaDoc.StaticFunctional
public class ScrapeArticles
{
    private ScrapeArticles() { }

    private static final String STARS =
        "*********************************************" +
        "********************************************\n";

    /**
     * This is used to do the downloading of newspaper articles.
     *
     * @param articleReceiver This is an instance of {@code ScrapedArticleReceiver}.  Whenever an
     * {@code Article} has successfully downloaded, it will be passed to this 'receiver' class.  
     * There is a pre-written, standard {@code ScrapedArticleReceiver} that writes to a directory
     * on the file-system as {@code Article's} are downloaded.  If there is a need to transmit
     * downloaded {@code Article's} elsewhere, implement that  {@code interface}, and provide an
     * instance of it to this parameter.
     *
     * @param articleURLs this is a parameter that should have been generated by a call to method:
     * {@code ScrapeURLs.getArticleURLs(...)}
     *
     * @param articleGetter This is basically a "Post-Processor" for HTML Web-based newspaper 
     * articles. This parameter cannot be null.  It is just a simple, one-line, lambda-predicate
     * which needs to be implemented by the programmer.  Internet news websites (such as: 
     * {@code news.yahoo.com, cnn.com}, and {@code gov.cn}) have News-Articles on pages that 
     * contain a lot of extraneous and advertising links and content.  This parameter needs to
     * extract the {@code Article}-body content from the rest of the page.  <I>This is usually 
     * very trivial, but it is also mandatory.</I>  Read about the  {@code class ArticleGet} for
     * more information about extracting the news-content from a Newspaper {@code Article}
     * web-page.
     *
     * @param skipArticlesWithoutPhotos This may be {@code TRUE}, and if it is - articles that
     * contain only textual content will be skipped.  This can be useful for foreign-news sources
     * where the reader is usually working-harder to understand the content in the first place.
     * This class is primarily used with foreign-news content websites.  As such, staring at 
     * pages of Mandarin Chinese or Spanish is usually a lot easier if there is at least one 
     * photo on the page.  This parameter allows users to skip highly dense articles that do not
     * contain at least one picture.
     *
     * @param bannerAndAdFinder This parameter may be null, but if it is not, it will be used to
     * skip banner-advertisement images.  This parameter, in reality, does very little.  It
     * will not actually be used to eliminated advertising images - <I>but rather only to identify
     * when an image is a banner, advertisement, or spurious picture</I>.  Since this is a news
     * web-site scraping Java Package, there is a part that allows a user to require that only news
     * paper articles that contain a photo be downloaded - and the real purpose of including the
     * {@code 'bannerAndAdFinder'} is to allow the scrape mechanism to 'skip' articles whose only
     * photos are advertisements.
     * 
     * <BR /><BR /><B>NOTE:</B> Again, the primary impetus for developing these tools was for 
     * scraping and translating news articles from foreign countries like Spain, China, and parts
     * of South America.  It could be used for any news-source desired.  When reading foreign
     * language text - it helps "a little bit more" to see a picture.  This parameter is solely 
     * used for that purpose.
     * 
     * <BR /><BR /><B>PRODUCT ADVERTISEMENTS &amp; FACEBOOK / TWITTER LINKS:</B> Removing actual
     * links about "pinning to Reddit.com" or "Tweeting" articles can be done using either:
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@link ArticleGet} - Writing an instance of {@code ArticleGet} that <B>NOT ONLY</B> 
     *      extracts the body of a newspaper-article, <B>BUT ALSO</B> performs HTML cleanup using
     *      the {@code 'Remove'} method of the NodeSearch Package.
     * </LI>
     * <LI> {@link HTMLModifier} - Writing a "cleaner" version of the {@code HTMLModifier} lambda
     *      expression / {@code Function Interface} can also use the NodeSearch classes for
     *      removing annoying commercials - or buttons about "Sharing a link on Facebook."  The
     *      class {@link ToHTML} provides a window for accepting an instance of
     *      {@code HTMLModifier} when converting the generated serialized-data HTML
     *      {@code Vector's} into {@code '.html' index} files.
     * </LI>
     * </UL>
     *
     * @param keepOriginalPageHTML When this is {@code TRUE}, the original page html will be stored
     * in the result set.  When this is {@code FALSE} null shall be stored in place of the original
     * page data.
     *
     * <BR /><BR /><B>NOTE:</B> The original page HTML is the source HTML that is fed into the
     * {@code ArticleGet} lambda.  It contains the "pre-processed HTML."
     *
     * @param pause If there are many / numerous articles to download, pass an instance of
     * {@code class Pause}, and intermediate progress can be saved, and reloaded at a later time.
     *
     * @param log This parameter may not be null, or a {@code NullPointerException} shall throw.
     * As articles are downloaded, notices shall be posted to this {@code 'log'} by this method.
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @return A {@code Vector} that is <B><I>exactly</B></I> parallel to the input
     * {@code Vector<Vector<String>> articleURLs} will be returned.  Each element of each of the
     * sub-{@code Vector's} in this two-dimensional {@code Vector} will have an instance of the
     * enumerated-type {@code 'DownloadResult'}.  The constant-value in {@code 'DownloadResult'}
     * will identify whether or not the {@code Article} pointed to by the {@code URL} at that
     * {@code Vector}-location successfully downloaded.
     * <BR /><BR />If the download failed, then the value of the {@code enum 'DownloadResult'} 
     * will be able to identify the error that occurred when attempting to scrape a particular
     * news-story {@code URL} 
     *
     * @throws PauseException If there is an error when attempting to save the download state.
     *
     * @throws ReceiveException If there are any problems with the {@code ScrapedArticleReceiver}
     * <BR /><BR /><B>NOTE:</B> A {@code ReceiveException} implies that the user's code has failed
     * to properly handle or save an instance of {@code Article} that has downloaded, successfully,
     * by this {@code class ScrapeArticles}.  A {@code ReceiveException} will halt the download
     * process immediately, and download state will be saved if the user has provided a reference
     * to the {@code Pause} parameter.
     *
     * <BR /><BR /><B>NOTE:</B> Other internally caused download-exceptions will be handled and
     * logged (<I>without halting the entire download-process</I>) - and downloading will continue.  
     * A note about the internally-produced exception will be printed to the log, and an 
     * appropriate instance of {@code enum DownloadResult} will be put in the return
     * {@code Vector}.
     *
     * @throws IOException This exception is required for any method that uses Java's
     * {@code interface java.lang.Appendable}.  Here, the {@code 'Appendable'} is the log, and if
     * writing to this user provided {@code 'log'} produces an exception, then download progress
     * will halt immediately, and download state will be saved if the user has provided a reference
     * to the {@code Pause} parameter.
     */
    public static Vector<Vector<DownloadResult>> download(   
        ScrapedArticleReceiver  articleReceiver,
        Vector<Vector<String>>  articleURLs,
        ArticleGet              articleGetter,
        boolean                 skipArticlesWithoutPhotos,
        StrFilter               bannerAndAdFinder,   
        boolean                 keepOriginalPageHTML,
        Pause                   pause,
        Appendable              log
    )
        throws PauseException, ReceiveException, IOException
    {
        log.append(
            "\n" + BRED + STARS + STARS +
            RESET + " Downloading Articles" + BRED + "\n" +
            STARS + STARS + RESET + '\n'
        );

        // The loop variables, and the return-result Vector.
        int                             outerCounter    = 0;
        int                             innerCounter    = 0;
        int                             successCounter  = 0;
        boolean                         firstIteration  = true;
        Vector<Vector<DownloadResult>>  ret             = null;
        URL                             url             = null;
        Runtime                         rt              = Runtime.getRuntime();

        // If the user has passed an instance of 'pause' then it should be loaded from disk.
        if (pause != null)
        {
            Ret4<Vector<Vector<DownloadResult>>, Integer, Integer, Integer> r = pause.loadState();

            ret             = r.a;
            outerCounter    = r.b.intValue();
            innerCounter    = r.c.intValue();
            successCounter  = r.d.intValue();
        }

        // If the user did not provide a "Pause" mechanism, **OR** the "Pause Mechanism" asserts
        // that the download process is starting from the beginning of the article-URL Vector,
        // THEN a *new vector* should be built.
        if (    (pause == null)
            ||  ((outerCounter == 0) && (innerCounter == 0) && (successCounter == 0))
        )
        {
            // Need to instantiate a brand new return vector.  The downloader is starting over
            // at the beginning of the Article URL list.

            ret = new Vector<>(articleURLs.size());

            // Initializes the capacity (sizes) of the two-dimensional "Return Vector."
            //
            // NOTE: The return Vector is exactly parallel to the input "articleURLs"
            //       two-dimensional input Vector.

            for (int i=0; i < articleURLs.size(); i++) 
                ret.add(new Vector<DownloadResult>(articleURLs.elementAt(i).size()));
        }

        for (; outerCounter < articleURLs.size(); outerCounter++)
        {
            // System.out.println("outerCounter=" + outerCounter + ", innerCounter=" +
            //      innerCounter + ", articleURLs.size()=" + articleURLs.size());

            // System.out.println("articleURLs.elementAt(" + outerCounter + ").size()=" +
            //      articleURLs.elementAt(outerCounter).size());

            for (   innerCounter = (firstIteration ? innerCounter : 0);
                    innerCounter < articleURLs.elementAt(outerCounter).size();
                    innerCounter++
                )

                try
                {
                    firstIteration = false;
                    String urlStr = articleURLs.elementAt(outerCounter).elementAt(innerCounter);

                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Instantiate the URL object from the URLStr String.
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    // Should never happen, because each URL will have been alredy tested 
                    // and instantiated in the previous method.

                    try
                        { url = new URL(urlStr); }

                    catch (Exception e)
                    {
                        log.append
                            ("Could not instantiate URL-String into URL for [" + urlStr + "].\n");

                        ret.elementAt(outerCounter).add(DownloadResult.BAD_ARTICLE_URL);
                        continue;
                    }


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Run the Garbage Collector, Print Article URL and Number to log.
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    rt.gc();
                    String              freeMem         = StringParse.commas(rt.freeMemory());
                    String              totalMem        = StringParse.commas(rt.totalMemory());

                    log.append(
                        "\nVisiting URL: [" +
                        YELLOW +  StringParse.zeroPad10e4(outerCounter) + RESET + 
                        " of " + StringParse.zeroPad10e4(articleURLs.size()) + ", " +
                        YELLOW +  StringParse.zeroPad10e4(innerCounter) + RESET + 
                        " of " + StringParse.zeroPad10e4
                            (articleURLs.elementAt(outerCounter).size()) + "] " +
                        CYAN         + " - "  + url                       + RESET + '\n' +
                        "Available Memory: "    + YELLOW +  freeMem       + RESET + '\t' +
                        "Total Memory: "        + YELLOW +  totalMem      + RESET + '\n'
                    );


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Scrape the web-page
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    int                 retryCount      = 0;
                    Vector<HTMLNode>    page            = null;

                    while ((page == null) && (retryCount < 5))

                        try
                            { page = HTMLPageMWT.getPageTokens(15, TimeUnit.SECONDS, url, false); }
    
                        catch (Exception e)
                        {
                            log.append(HTTPCodes.convertMessageVerbose(e, url, 1) + '\n');
                            retryCount++;
                        }


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Verify the results of scraping the web-page
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    if (page == null)
                    {
                        log.append(
                            BRED + "\tArticle could not download, max 5 retry counts." +
                            RESET + '\n'
                        );

                        ret.elementAt(outerCounter).add(DownloadResult.COULD_NOT_DOWNLOAD);
                        continue;
                    }

                    if (page.size() == 0)
                    {
                        log.append(
                            BRED + "\tArticle was retrieved, but page-vector was empty" +
                            RESET + '\n'
                        );

                        ret.elementAt(outerCounter).add(DownloadResult.EMPTY_PAGE_VECTOR);
                        continue;
                    }

                    log.append
                        ("\tPage contains (" + YELLOW + page.size() + RESET + ") HTMLNodes.\n");


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Retrieve the <TITLE> element (as a String) from the page - if it has one.
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    String title = Util.textNodesString(TagNodeGetInclusive.first(page, "title"));

                    if (title.length() > 0)
                        log.append
                            ("\tPage <TITLE> element is: " + YELLOW + title + RESET + '\n');

                    else
                        log.append("\tPage has no <TITLE> element, or it was empty.\n");


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Use the Article-Getter to get the Article-Body.  Watch for Exceptions.
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    Vector<HTMLNode> article = null;

                    // The function-pointer (FunctionInterface) 'articleGetter' is supposed to 
                    // locate and extract the Article's HTML from the surrounding web-page, which
                    // is usually fully-loaded with advertisements, and "See This Also" links.
                    //
                    // All news-websites I have seen wrap the article itself in an HTML <MAIN>
                    // <ARTICLE>, <SECTION role='article'> or a <DIV CLASS='main'> tag
                    // that is very easy to find.  Also, these tags differ from site-to-site, each
                    // site will use the same tag for all of its articles.
                    //
                    // (But you have to look at the HTML first)

                    try
                        { article = articleGetter.apply(url, page); }

                    catch (ArticleGetException e)
                    {
                        log.append(
                            BRED + "\tArticleGet.apply(...) failed: " + e.getMessage() +
                            RESET + "\nException Cause Chain:\n" + EXCC.toString(e) + '\n'
                        );

                        ret.elementAt(outerCounter).add(DownloadResult.ARTICLE_GET_EXCEPTION);
                        continue;
                    }


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Verify the results of article get, and choose the right DownloadResult
                    // Enumerated-Constant if the download failed
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    if (article == null)
                    {
                        log.append(
                            BRED + "\tContent-body not found by ArticleGet.apply(...)\n" +
                            RESET
                        );

                        ret.elementAt(outerCounter).add(DownloadResult.ARTICLE_GET_RETURNED_NULL);
                        continue;
                    }

                    if (article.size() == 0)
                    {
                        log.append(
                            BRED + "\tContent-body not found by ArticleGet.apply(...)\n" +
                            RESET
                        );

                        ret.elementAt(outerCounter)
                            .add(DownloadResult.ARTICLE_GET_RETURNED_EMPTY_VECTOR);
                        continue;
                    }

                    log.append(
                        "\tArticle body contains (" + YELLOW + article.size() + RESET +
                        ") HTMLNodes.\n"
                    );


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Retrieve the positions of the images
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    // The Vector-index location of all the images inside the article-body
                    int[] imagePosArr = InnerTagFind.all(article, "img", "src",
                        (String src) -> ! StrCmpr.startsWithXOR_CI(src.trim(), "data:"));

                    // A list of all the image-URL's that were extracted from the article-body
                    // using the integer-array aquired in the previous line.
                    Vector<URL> imageURLs = Links.resolveSRCs(article, imagePosArr, url);

                    if (skipArticlesWithoutPhotos && (imageURLs.size() == 0))
                    {
                        log.append(
                            BRED + "\tArticle content contained 0 HTML IMG elements" + RESET +
                            '\n'
                        );

                        ret.elementAt(outerCounter).add(DownloadResult.NO_IMAGES_FOUND);
                        continue;
                    }

                    log.append(
                        "\tArticle contains (" + YELLOW + imageURLs.size() + RESET + ") " +
                        "image TagNodes.\n"
                    );


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Check the banner-situation.  Count all images, and less that number by the
                    // number of "banner-images"
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    // IMPORTANT NOTE: THIS ISN'T ALWAYS USEFUL OR USEABLE...  IT IS **SOMETIMES**
                    // USEFUL

                    int imageCount = imageURLs.size();

                    if (bannerAndAdFinder != null)

                        for (int pos : imagePosArr)

                            if (bannerAndAdFinder
                                .test(((TagNode) article.elementAt(pos)).AV("src"))
                            )
                                imageCount--;

                    if (skipArticlesWithoutPhotos && (imageCount == 0))
                    {
                        log.append(
                            BRED + "\tAll images inside article were banner images" +
                            RESET + '\n'
                        );

                        ret.elementAt(outerCounter)
                            .add(DownloadResult.NO_IMAGES_FOUND_ONLY_BANNERS);

                        continue;
                    }

                    if (bannerAndAdFinder != null)

                        log.append(
                            "\tArticle contains (" + YELLOW + imageCount + RESET + ") " +
                            "non-banner image TagNodes.\n"
                        );


                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Write the results to the output file
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    Article articleResult = new Article(
                        url, title, (keepOriginalPageHTML ? page : null), article, imageURLs,
                        imagePosArr
                    );

                    // The article was successfully downloaded and parsed.  Send it to the
                    // "Receiver" and add DownloadResult to the return vector.

                    log.append(
                        GREEN + "ARTICLE LOADED." + RESET +
                        "  Sending to ScrapedArticleReceiver.\n"
                    );

                    articleReceiver.receive(articleResult, outerCounter, innerCounter);
                    ret.elementAt(outerCounter).add(DownloadResult.SUCCESS);

                    successCounter++;

                }
                catch (ReceiveException re)
                {
                    // NOTE: If there was a "ReceiveException" then article-downloading must be
                    //       halted immediately.  A ReceiveException implies that the user did not
                    //       properly handle the downloaded Article, and the user's code would have
                    //       to be debugged.

                    log.append(
                        "There was an error when attempting to pass the downloaded article to " +
                        "the ArticleReceiver.  Unrecoverable.  Saving download state, and " +
                        "halting download.\n"
                    );

                    // Make sure to save the internal download state                        
                    if (pause != null)
                        pause.saveState(ret, outerCounter, innerCounter, successCounter);

                    // Make sure to stop the download process now.  If the article "Receiver"
                    // failed to save or store a received-article, there is NO POINT IN CONTINUING
                    // THE DOWNLOADER.
                    //
                    // NOTE: This will cause the method to exit with error, make sure to stop the
                    //       "MWT Thread" Remember, this is just a simple "Monitor Thread" that 
                    //       prevents a download from hanging.

                    HTMLPageMWT.shutdownMWTThreads();

                    throw re;
                }
                catch (IOException ioe)
                {
                    // This exception occurs if writing the "Appendable" (the log) fails.  If this
                    // happens, download should halt immediately, and the internal-state should be
                    // saved to the 'pause' variable.

                    if (pause != null)
                        pause.saveState(ret, outerCounter, innerCounter, successCounter);

                    // Need to stop the download process.  IOException could ONLY BE the result of
                    // the "Appendable.append" method.  None of the other stuff throws IOException.
                    //
                    // ALSO: If the "Appendable" never fails (which is 99% likely not to happen),
                    // This catch-statement will never actually execute.  However, if Appendable
                    // did, in fact, fail to write - then downloading cannot continue;
                    //
                    // NOTE: This will cause the method to exit with error, make sure to stop the
                    //       HTMLPage's "MWT Thread" (It is a simple "Monitor Thread") that 
                    //       can be used to prevent the download from hanging.
                    //       HOWEVER, it will also cause the JVM to 'hang' this thread exits
                    //       without shutting down the monitor-thread!

                    HTMLPageMWT.shutdownMWTThreads();

                    throw ioe;
                }
                catch (Exception e)
                {
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Handle "Unknown Exception" case.
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
  
                    log.append(
                        "There was an unknown Exception:\n" + EXCC.toString(e) +
                        "\nSkipping URL: " + url + '\n'
                    );

                    ret.elementAt(outerCounter).add(DownloadResult.UNKNOWN_EXCEPTION);
                }
                finally
                {
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                    // Write the current "READ STATE" information (two integers)
                    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                    // This makes sure that the download-progress is not lost when large numbers
                    // of articles are being processed.  Restart the download, and the loop
                    // variables will automatically be initialized to where they were before the
                    // JVM exited.  (Pretty Useful)

                    if (pause != null)
                        pause.saveState(ret, outerCounter, innerCounter, successCounter);
                }
        }

        log.append(
            BRED + STARS + RESET +
            "Traversing Site Completed.\n" +
            "Loaded a total of (" + successCounter + ") articles.\n"
        );

        // Returns the two-dimensional "Download Result" Vector
        // Make sure to stop the "Max Wait Time Threads"

        HTMLPageMWT.shutdownMWTThreads();

        return ret;
    }

}