package Torello.HTML.Tools.Images;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// My Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

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

import Torello.HTML.NodeSearch.TagNodeFind;
import Torello.Java.Additional.Ret2;
import Torello.Java.Additional.AppendableLog;
import Torello.Java.Additional.AppendableSafe;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// JDK Imports.  These are all spelled-out at the bottom, because none of them are commonly used.
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

// ByteArrayOutputStream, File, IOException
import java.io.*;

// Callable, Executors, ExecutorService
import java.util.concurrent.*;

import java.net.URL;
import java.net.HttpURLConnection;
import java.util.Vector;
import java.util.regex.Matcher;
import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.ReentrantLock;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;

/**
 * A more advanced class for both downloading and saving a list of images, using URL's.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=ISR>
 */
@Torello.JavaDoc.StaticFunctional
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="IMAGE_SCRAPER_CLASS")
public class ImageScraper
{
    // This Class is Static-Functional, and does not have any program state, other than the monitor
    // Thread.  There is no need for a public-constructor, or any constructor for that matter.

    private ImageScraper() { }

    // Helps "FIND" the bugs.  There are only 6 extra boolean-comparisons for a println
    // There is no need to delete this right now.

    private static final boolean DEBUGGING = false;


    // ********************************************************************************************
    // ********************************************************************************************
    // RECORD: Used as ImageScraper class Top-Level Data-Flow **AND** Helper-Function
    // ********************************************************************************************
    // ********************************************************************************************


    // Simple "Record" that makes passing these parameters all around wily-nilly a lot easier
    // Used Strictly Internally to this class
    //
    // There turns out to be a lot of "data" in both the form of "configurations", and even more
    // that is saved and returned to the user after completion.  This RECORD right here saves all
    // of the data, and keeps inside ... well ... one single (top-level) reference.

    private static class RECORD
    {
        private static final String I4 = "    ";


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Constant (final) for the ENTIRETY of the download-process
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Request           request;
        final Results           results;
        final AppendableLog     al;
        final AppendableSafe    log;

        // Has a non-null log
        final boolean hasLog;

        // Verbosity-Level that is Strictly Equal-To
        final boolean logLevelEQ1;
        final boolean logLevelEQ2;
        final boolean logLevelEQ3;

        // Verbosity-Level that is Greater-Than or Equal-To
        final boolean logLevelGTEQ1;
        final boolean logLevelGTEQ2;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // These change with each loop iteration
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Reference-Fields
        URL         url             = null;
        String[]    b64ImageData    = null;
        ImageInfo   imageInfo       = null;

        // Boolean-Primitive
        boolean isB64EncodedImage = false;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Constructor
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        RECORD(Request request, Results results, AppendableLog al)
        {
            this.request    = request;
            this.results    = results;
            this.al         = al;
            this.log        = al.log;

            // If there is a non-null log, set the boolean stating that there is a log
            this.hasLog = (al.log != null);

            // DEBUGGING:
            // System.out.println("hasLog: " + hasLog + ", al.level: " + al.level);
            // if (! Q.YN("Continue?")) System.exit(0);

            // Makes Verbose-Printing Code neater and easier to look at.
            this.logLevelEQ1 = hasLog && (al.level == 1);
            this.logLevelEQ2 = hasLog && (al.level == 2);
            this.logLevelEQ3 = hasLog && (al.level == 3);

            // Also Makes Verbosity Faster & Easier to Read
            this.logLevelGTEQ1 = hasLog && (al.level >= 1);
            this.logLevelGTEQ2 = hasLog && (al.level >= 2);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Some Simple Methods
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // This is called at the very beginning of the Primary Download-Loop, directly at the top
        // of the loop-body.  It s the first thing that is done on each iteration of the download.
        //
        // NOTE: This resets all NON-FINAL fields in this class.

        void reset()
        {
            this.url                = null;
            this.b64ImageData       = null;
            this.imageInfo          = null;
            this.isB64EncodedImage  = false;
        }

        void append(String s)   { log.append(s); }
        void appendI4(String s) { log.append(I4).append(s); }

        // This is always a useful debugging tool, both now, and possibly in the future
        public String toString()
        {
            return
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // Constant (final) for the ENTIRETY of the download-process
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 

                "RECORD's 'final' Fields (Constant through-out entire-download):\n" +

                // final Request request;
                I4 + "this.request:        " + ((this.request != null) ? "non-" : "") + "null\n" +

                // final Results results;
                I4 + "this.results:        " + ((this.results != null) ? "non-" : "") + "null\n" +

                // final AppendableLog al;
                I4 + "this.AppendableLog:  " + ((this.al != null) ? "non-" : "") + "null\n" +

                // final AppendableSafe log;
                I4 + "this.AppendableSafe: " + ((this.log != null) ? "non-" : "") + "null\n" +

                // final boolean hasLog;
                I4 + "this.hasLog:         " + this.hasLog + '\n' +

                // final boolean logLevelEQ1;
                I4 + "this.logLevelEQ1:    " + this.logLevelEQ1 + '\n' +

                // final boolean logLevelEQ2;
                I4 + "this.logLevelEQ2:    " + this.logLevelEQ2 + '\n' +

                // final boolean logLevelEQ3;
                I4 + "this.logLevelEQ3:    " + this.logLevelEQ3 + '\n' +

                // final boolean logLevelGTEQ1;
                I4 + "this.logLevelGTEQ1:  " + this.logLevelGTEQ1 + '\n' +

                // final boolean logLevelGTEQ2;
                I4 + "this.logLevelGTEQ2:  " + this.logLevelGTEQ2 + '\n' +


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // These change with each loop iteration
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 

                "Fields that change on each Loop-Iteration:\n" +

                // URL url = null;
                I4 + "this.url:               " +
                    ((this.url != null) ? url.toString() : "null") + '\n' +

                // String[] b64ImageData = null;
                I4 + "this.b64ImageData:      " +
                    ((this.b64ImageData != null) ? "non-" : "") + "null\n" +

                // ImageInfo imageInfo = null;
                I4 + "this.imageInfo:         " +
                    ((this.imageInfo != null) ? "non-" : "") + "null\n" +

                // boolean isB64Image = false;
                I4 + "this.isB64EncodedImage: " + this.isB64EncodedImage + '\n';
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Helpers that SIMULTANEOUSLY write-results to 'Results' and write-log to 'AppendableLog'
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Simple Helper for Printing to the Appendable log
        void printEx(String operation, Throwable t)
        {
            this.al.append(
                "    The " + operation + " Code has thrown an Exception:\n" +
                "        Throwable Class: " + t.getClass().getName() + '\n' +
                "        Message:         [" + t.getMessage() + "]\n"
            );

            while ((t = t.getCause()) != null) this.al.append(
                "            Caused by Throwable Class: " + t.getClass().getName() + '\n' +
                "            Message:                   [" + t.getMessage() + "]\n"
            );
        }

        // There are 4 different User-Provided Lambda-Targets.  If they throw an exception (which
        // should be extremely rare), this method is called.
        //
        // NOTE: This method only works if "RECORD.imageInfo" is NON-NULL.  This means that the
        //       first couple of User-Provided Lambda's have to use "reportEx" instead!

        <T> T userLambdaEx(String userLambdaName, Exception e) throws ImageScraperException
        {
            this.results.userLambdaException(this.imageInfo, e);

            final String errMsg =
                "While attempting to invoke the User-Provided Lambda-Target" +
                "'Request." + userLambdaName + "', an exception was thrown by the code.";

            if (this.request.skipOnUserLambdaException)
            {
                if      (this.logLevelEQ1) this.append("x ");
                else if (this.logLevelEQ2) this.appendI4(errMsg + '\n');
                else if (this.logLevelEQ3) this.printEx("Invoke User '" + userLambdaName +"'", e);

                return null;
            }

            else throw new ImageScraperException
                (errMsg + ".  Please see Throwable.getCause() for more details.", e);
        }

        <T> T reportEx(boolean skipBool, String errMsg, String operationName, Exception e)
            throws ImageScraperException
        {
            // Paranoia & Sanity (A Simple Check)  (An 'assert' that should never happen)
            if (e == null) throw new UnreachableError();

            this.results.exceptionFail(this.url, e);

            if (skipBool)
            {
                if      (this.logLevelEQ1) this.append("x ");
                else if (this.logLevelEQ2) this.appendI4(errMsg + '\n');
                else if (this.logLevelEQ3) this.printEx(operationName, e);

                return null;
            }

            else throw ImageScraperException.class.isAssignableFrom(e.getClass())
                ? ((ImageScraperException) e)
                : new ImageScraperException(errMsg + ".  See Throwable.geCause() for details.", e);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Thread-Related Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If this class has been used to make "multi-threaded" calls that use a Time-Out wait-period,
     * you might see your Java-Program hang for a few seconds when you would expect it to exit back
     * to your O.S. normally.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Before Exiting:</B>
     * 
     * <BR />When a program you have written reaches the end of its code, if you have performed any
     * time-dependent Image-Downloads using this class (class {@code ImageScraper}), then your
     * program <I>might not exit immediately,</I> but rather sit at the command-prompt for anywhere
     * between 10 and 30 seconds before this Timeout-Thread dies.
     *
     * <BR /><BR />Note that you may immediately terminate any additional threads that were started
     * using this method.
     */
    public static void shutdownTOThreads() { executor.shutdownNow(); }

    // This class is Static-Functional, and these are the only class-fields.  They are both final,
    // and the 'lock' variable is used to ensure that the class is, indeed, Thread-Safe.

    private static final ExecutorService    executor    = Executors.newCachedThreadPool();
    private static final Lock               lock        = new ReentrantLock();


    // ********************************************************************************************
    // ********************************************************************************************
    // Primary User-API Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Downloads images located inside an HTML Page and updates the {@code SRC=...} {@code URL's}
     * so that the links point to a <I>local copy</I> of <I>local images</I>.
     *
     * <BR /><BR />After completion of this method, an HTML page which contained any HTML image
     * elements will have had those images downloaded to the local file-system, and also have had 
     * the HTML attribute {@code 'src=...'} changed to reflect the local image name instead of the
     * Internet URL name.
     *
     * @param page Any vectorized-html page or subpage.  This page should have HTML {@code <IMG ...>}
     * elements in it, or else this method will exit without doing anything.
     *
     * @param pageURL If any of the HTML image elements have {@code src='...'} attributes that are
     * partially resolved or <I>relative {@code URL's}</I> then this can be passed to the
     * {@code ImageScraper} constructors in order to convert partial or relative {@code URL's}
     * into complete {@code URL's.}  The Image Downloader simply cannot work with partially
     * resolved {@code URL's}, and will skip them if they are partially resolved.  This parameter
     * may be null, but if it is and there are incomplete-{@code URL's} those images will
     * simply not be downloaded.
     *
     * @param log This is the 'logger' for this method.  It may be null, and if it is - no output
     * will be sent to the terminal.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @param targetDirectory This File-System directory where these files shall be stored.
     *
     * @return An instance of {@code Ret2<int[], Results>}.  The two returned elements
     * of this class include:
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@code Ret2.a (int[])}
     *      <BR /><BR />This shall contain an index-array for the indices of each HTML
     *      {@code '<IMG SRC=...>'} element found on the page.  It is not guaranteed that each of
     *      images will have been resolved or downloaded successfully, but rather just that an HTML
     *      {@code 'IMG'} element that had a {@code 'SRC'} attribute.  The second element of this
     *      return-type will contain information regarding which images downloaded successfully.
     *      <BR /><BR />
     * </LI>
     * <LI> {@code Ret2.b (Results)}
     *      <BR /><BR />The second element of the return-type shall be the instance of
     *      {@link Results} returned from the invocation of
     *      {@code ImageScraper.download(...)}.  This method will provide details about each of the
     *      images that were downloaded; or, if the download failed, the reasons for the failure.
     *      <I>This return element shall be null if no images were found on the page.</I>
     *      <BR />
     * </LI>
     * </UL>
     * 
     * <BR />These return {@code Object} references are not necessarily important - <I>and they
     * may be discarded if needed.</I>  They are provided as a matter of utility if further
     * verification or research into successful downloads is needed.
     * 
     * @throws IOException I/O Problems that weren't avoided.
     * @throws ImageScraperException Thrown for any number of errors that went unsuppressed.
     */
    public static Ret2<int[], Results> localizeImages
        (Vector<HTMLNode> page, URL pageURL, Appendable log, String targetDirectory)
        throws IOException, ImageScraperException
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Find all of the Image TagNode's on the Input Web-Page
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        int[]           imgPosArr   = TagNodeFind.all(page, TC.Both, "img");
        Vector<TagNode> vec         = new Vector<>();

        // No Images Found.
        if (imgPosArr.length == 0) return new Ret2<int[], Results>(imgPosArr, null);

        for (int pos : imgPosArr) vec.addElement((TagNode) page.elementAt(pos));


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build a Request and Download all of the Image's that were just found / identified
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Request request = Request.buildFromTagNodeIter(vec, pageURL, true);
        request.targetDirectory = targetDirectory;

        // NOTE: This is NOT FINISHED:
        // SET ALL OF THE "Skip On Exception" booleans to TRUE!!!

        // Invoke the Main Image Downloader
        Results r = ImageScraper.download(request, log);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Replace the <IMG SRC=...> TagNode URL's for images that were successfully downloaded.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Now replace 
        ReplaceFunction replacer = (HTMLNode n, int arrPos, int count) ->
        {
            if (r.skipped[count] == false)

                return ((TagNode) page.elementAt(arrPos))
                        .setAV("src", r.fileNames[count], SD.SingleQuotes);

            else return (TagNode) n;
        };
    
        ReplaceNodes.r(page, imgPosArr, replacer);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Report the Results
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        return new Ret2<int[], Results>(imgPosArr, r);
    }

    /**
     * This will iterate through the {@code URL's} and download them.  Note that parameter
     * {@code 'log'} may be null, and if so, it will be quietly ignored.
     *
     * @param request This parameter takes customization requests for batch image downloads.  To
     * read more information about how to configure a download, please review the documentation for
     * the class {@link Request}.
     *
     * <BR /><BR />Note that upon entering this method, this parameter is immediately cloned to
     * prevent the possibility of Thread Concurrency Problems from happening.  After cloning, the
     * the cloned instance is used exclusively, and the original parameter is discarded.  Further
     * changes to the parameter-instance will not have any effect on the process.
     * 
     * @param log This shall receive text / log information.  This parameter may receive null, and
     * if it does it will be ignored.  When ignored, logging information will not printed.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @return an instance of {@code class Results} for the download.  The {@link Results} class
     * contains several parallel arrays with information about images that have downloaded.  If an
     * image-download happens to fail due to an improperly formed {@code URL} (or an 'incorrect' 
     * {@code URL}), then the information in the {@code Results} arrays will contain a 'null' value
     * for the index at those array-positions corresponding to the failed image.
     *
     * @throws ImageScraperException Thrown for any number of exceptions that may be thrown while
     * executing the download-loop.  If another exception is thrown, then it is wrapped by this
     * class' exception ({@link ImageScraperException}), and set as the {@code 'cause'} of that
     * exception.
     * 
     * @throws AppendableError The interface {@code java.lang.Appendable} was designed to allow for
     * an implementation to throw the (unchecked) exception {@code IOException}.  This has many 
     * blessings, but can occasionally be a pain since, indeed, {@code IOException} is both an
     * unchecked exception (and requires an explicity catch), and also very common
     * (even ubiquitous) inside of HTTP download code.
     * 
     * <BR /><BR />If the user-provided {@code 'log'} parameter throws an {@code IOException} for
     * simply trying to write character-data to the log about the download-progress, then <I>an
     * {@code AppendableError} will be thrown</I>.  Note that this throwable does inherit 
     * {@code java.lang.Error}, meaning that it won't be caught by standard Java {@code catch}
     * clauses <I>(unless {@code 'Error'} is explicity mentioned!)</I>
     */
    public static Results download(Request request, Appendable log)
        throws ImageScraperException
    {
        // Clone the Request, Similar to "SafeVarArgs" - Specifically, if the user starts playing
        // with the contents of this class in the middle of a download, it will not have any effect
        // on the 'request' object that is actually being used.

        request = request.clone();        
    
        // Runs a few tests to make sure there are no problems using the request
        request.CHECK();

        // Makes log printing easier and easier.
        AppendableLog al = new AppendableLog(log, request.verbosity);

        // Main Request-Configuration and Response Class Instances.
        Results results = new Results(request.size);

        // Private, Internal Static-Class.  Makes passing variables even easier
        RECORD r = new RECORD(request, results, al);

        // Now, this just gets rid of the surrounding try-catch block.  This is the only real
        // reason for the internal/private method 'downloadWithoutTryCatch'.  This makes the
        // indentation look a lot better.  Also, in this method, the 'log' is replaced with the
        // AppendableSafe log

        try 
        {
            mainDownloadLoop(r);
            return results;
        }

        catch (ImageScraperException e)
        {
            // If an exception causes the system to stop/halt, this extra '\n\n' makes the output
            // text look a little nicer (sometimes... Sometimes it already looks fine).
            // No more no less.

            if (al.hasLog) al.append("\n\nThrowing ImageScraperException...\n");
            throw e;
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Main Download Iterator-Loop Method
    // ********************************************************************************************
    // ********************************************************************************************


    private static void mainDownloadLoop(RECORD r) throws ImageScraperException
    {
        // Helps prepare for the printing loop;
        if (r.logLevelGTEQ1) r.append("\n");

        // The "Main Benefit" of having a "Loop-Body" Method is to make the code below in the
        // actual Loop-Body have one-less-level-of-indentation.  That's really the only point of
        // doing this - whatsoever!
        //
        // NOTE: Remember that all the 'continue' commands inside "loopBody" had to be changed
        //       into 'return' commands

        for (URL url : r.request.source())
        {
            r.reset();
            r.url = url;
            loopBody(r);
        }
    }

    private static void loopBody(RECORD r) throws ImageScraperException
    {
        // Print URL-Iterable Number (request.counterPrinter)
        if (r.logLevelEQ1)
            r.append(r.request.counterPrinter.apply(r.results.pos) + ": ");

        if (r.logLevelGTEQ2)
            r.append("\n" + r.request.counterPrinter.apply(r.results.pos) + ": ");

        if (DEBUGGING) System.out.println("HERE: 01 (" + r.results.pos + ")");


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // DECIDE: Which of the three cases this is: URL, B64-Image, or an Exception-URL
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // If there was an Image-URL next, then print it !!!
        if (r.url != null)
            { if (r.logLevelGTEQ2) r.append("Image-URL: [" + r.url.toString() + "]\n"); }

        // If There was no URL, Then this is likely a B64-Encoded Image
        else if ((r.b64ImageData = r.request.nextB64Image()) != null)
        {
            r.isB64EncodedImage = true;

            if (r.logLevelGTEQ2) r.append(
                "BASE-64 IMAGE: " + r.b64ImageData[0] /* imageFormatStr */ + ',' +
                StrPrint.abbrev(r.b64ImageData[1], 35, true, " ... ", 70) + '\n'
            );
        }

        // If url is null, and this isn't a "B64-Encoded", then it's an Exception-Throw URL
        else
            { dealWithExceptionURL(r);  return; }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // DOWNLOAD & CONVERT
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (DEBUGGING) System.out.println("HERE: 02 (" + r.results.pos + ")");

        // If the user provided a 'urlPreProcessor' in his Request-instance, run that now.
        doUserURLPreProcessorIfNeeded(r);

        if (DEBUGGING) System.out.println("HERE: 03 (" + r.results.pos + ")");

        // Get the java.awt.image.BufferedImage instance
        Ret2<BufferedImage, IF> ret2BufferedImage = r.isB64EncodedImage
            ? convertB64Image(r)
            : downloadImage(r);

        if (DEBUGGING) System.out.println("HERE: 04 (" + r.results.pos + ")");

        // If 'null' is returned, The User Requested 'skipOn...' SO - skip-and-move-on.
        //    * Log-Messages will ALREADY have been printed
        //    * class Results array's will ALREADY have been updated. 
        //    * If an ImageScraperException is needed, it would ALREADY have been thrown.

        if (ret2BufferedImage == null) return;

        // Convert java.awt.image.BufferedImage into a byte[]-Array
        // This 'r2' contains the Image as a byte[]-Array, and the format in which it was saved

        Ret2<byte[], IF> ret2ByteArrImage = writeBufferedImageToByteArray
            (r, ret2BufferedImage.a /* The Image */, ret2BufferedImage.b /* The Extension */);

        if (DEBUGGING) System.out.println("HERE: 05 (" + r.results.pos + ")");

        // SAME AS PREVIOUS if (...) return;
        if (ret2ByteArrImage == null) return;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // SAVE THE IMAGE (or send to 'Request.imageReceiver')
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Now Build an "ImageInfo" instance. (This is sent to any/all User's Lambdas)
        // NOTE: No error-checking needed for a class that is strictly a data / "RECORD" class

        r.imageInfo = new ImageInfo(
            // Image-URL (very common)
            r.url,

            // Base-64 Image Stuff (rare, but not impossible)
            r.isB64EncodedImage,
            (r.isB64EncodedImage ? r.b64ImageData : null),

            // The actual downloaded and converted images, themselves
            ret2BufferedImage.a,    // java.awt.image.BufferredImage
            ret2ByteArrImage.a,     // byte[] imgByteArr

            // URL-Aquired Extension & Decided-Upon Extension
            ret2BufferedImage.b,    // guessedExt
            ret2ByteArrImage.b,     // actualExt

            // Results Array Counters
            r.results.pos,
            r.results.successCounter
        );

        if (DEBUGGING) System.out.println("HERE: 06 (" + r.results.pos + ")");

        // Save to Disk, or Send to Request.imageReceiver
        handleImageByteArray(r);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "Exception URL's" - Rare, but happens if the Static-Builder threw an Exception
    // ********************************************************************************************
    // ********************************************************************************************


    private static void dealWithExceptionURL(RECORD r)
    {
        // "Exception-URL's" are URL's that must have come from the static "TagNode"
        // Builders in class Request.  It happens when a complete-URL cannot be built
        // from a partial-URL, and the Links-Class saved the Exception in a Vector,
        // so that it can be reported to the user (righ here!)

        Exception e = r.request.nextTNSRCException();

        // ASSERT-STATEMENT: The 'request' instance should always return an 'e' here
        if (e == null) throw new UnreachableError();

        // Since this "Failed", make sure to let the "Results" object-instance know.
        r.results.tagNodeSRCError(e);

        // Now let the user know too
        if (r.hasLog) 
        {
            if (r.logLevelEQ1) r.append(" x ");

            else if (r.logLevelGTEQ2) r.append
                ("URL-Building Exception: " + e.getClass().getName() + '\n');

            if (r.logLevelEQ3) r.appendI4("Message: " + e.getMessage() + '\n');
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // User-Provided URL-PreProcessor (Maybe!)
    // ********************************************************************************************
    // ********************************************************************************************


    private static void doUserURLPreProcessorIfNeeded(RECORD r) throws ImageScraperException
    {
        if ((r.url == null) || (r.request.urlPreProcessor == null)) return;

        try
        {
            r.url = r.request.urlPreProcessor.apply(r.url);

            if (r.logLevelGTEQ2) r.appendI4("Pre-Processor URL:" + r.url + '\n');
        }

        catch (Exception e)
        {
            final String msg =
                "While attempting to invoke the user provided lambda " +
                "'Request.urlPreProcessor', an exception was thrown by the user-code.";

            if (r.request.skipOnUserLambdaException)
            {
                if (r.logLevelGTEQ2)    r.appendI4(msg);
                if (r.logLevelEQ3)      r.printEx("Run URL-PreProcessor", e);
                if (r.logLevelEQ1)      r.append("x ");

                r.results.exceptionFail(r.url, e);

                return;
            }

            else throw new ImageScraperException
                (msg + "  Please see Throwable.getCause() for more details.", e);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Convert a B64-Image to a java.awt.image.BufferedImage instance
    // ********************************************************************************************
    // ********************************************************************************************


    private static Ret2<BufferedImage, IF> convertB64Image(RECORD r) throws ImageScraperException
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Internally, the request-class saves B64-Images as Two-Element String[]-Array's
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        String  imageFormatStr  = r.b64ImageData[0];
        String  b64EncodedImage = r.b64ImageData[1];


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Skipping B64-Images entirely is one of the boolean-options in 'Request'
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (r.request.skipBase64EncodedImages)
        {
            if      (r.logLevelEQ1)     r.append("x ");
            else if (r.logLevelGTEQ2)   r.appendI4
                ("Skipping - Skip Request for all Base64-Encoded Images\n");

            r.results.skipB64();

            return null;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Try to do the B64-Converstion
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        try
        {
            IF ext = IF.get(imageFormatStr);

            BufferedImage image = IF.decodeBase64ToImage(b64EncodedImage, ext);

            // SUCCESS!
            if (image != null) new Ret2<>(image, ext);
        }
    
        catch (Exception e)
        {
            // This call either returns null, or throws an ImageScraperException
            return r.reportEx(
                r.request.skipOnB64DecodeException,
                "Exception throw Java's Base-64 Image Decoder while decoding a Base-64 Image",
                "Base-64 Image Decoding",
                e
            );
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // ELSE: The Image was null, so use 'NullImageException'
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Exception niex = new NullImageException(
            "The B64-Image Encoding Regular-Expression matched the Source-URL, but " +
            "Java's B64-Image Decoder has returned null upon decoding it."
        );

        niex.fillInStackTrace();

        // Returns 'null', or throws an exception
        return r.reportEx(
            r.request.skipOnNullImageException,
            "Null Image returned by Java's B64 Image-Decoder",
            "Base-64 Image Decoding",
            niex
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Download an Image to a java.awt.image.BufferedImage instance
    // ********************************************************************************************
    // ********************************************************************************************


    private static Ret2<BufferedImage, IF> downloadImage(RECORD r) throws ImageScraperException
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Do the "Skipping URL" Lambda-Target right now (if the user's Request-Instance has one)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (r.request.skipURL != null)
        {
            try 
            {
                if (r.request.skipURL.test(r.url))
                {
                    // This *ISN'T* Exception-Case Code, it is a situation where the user has
                    // intentionally asked that this URL be skipped.
        
                    if (r.logLevelEQ1) r.append("x ");
    
                    if (r.logLevelGTEQ2)
                        r.appendI4("URL Skip-Predicate requests this URL be skipped.\n");
    
                    r.results.skippedURL(r.url);
                    return null;
                }
            }

            catch (Exception e)
            {
                // This call either returns null, or throws an ImageScraperException 
                // Depending upon the boolean 'r.request.skipOnUserLambdaException'
                //
                // NOTE: This **DOESN'T** return (for now).  This is actually a non-fatal exception
                //       and progress can actually continue

                r.reportEx(
                    r.request.skipOnUserLambdaException,
                    "Exception Thrown by User-Provided Lambda-Target 'Request.skipURL'",
                    "Invoke User 'Request.skipURL' Lambda-Target",
                    e
                );
            } 
        }
        

        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build a Monitor Thread Instance
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Callable<BufferedImage> threadDownloader = new Callable<BufferedImage>()
        {
            public BufferedImage call() throws ImageScraperException
            { return downloadImageCallable(r); }
        };


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Run the Monitor Thread, return the result... Or Handle the Exception (if there was one)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        lock.lock();
        Future<BufferedImage> future = executor.submit(threadDownloader);
        lock.unlock();

        try
        {
            BufferedImage bi = future.get(r.request.maxDownloadWaitTime, r.request.waitTimeUnits);

            return (bi == null)
                ? null
                : new Ret2<>(bi, IF.getGuess(r.url.toString()));
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // TimeoutException: Web-Server took longer 'Request.maxDownloadWaitTime'
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        catch (TimeoutException e)
        {
            // This call either returns null, or throws an ImageScraperException 
            // Depending upon the boolean 'r.request.skipOnTimeOutException'

            return r.reportEx(
                r.request.skipOnTimeOutException,
                "Waited: " + r.request.maxDownloadWaitTime + " " +
                    r.request.waitTimeUnits.toString(),
                "HTTP Image-Download",
                e
            );

            // OLD MESSAGE:
            // "The download source-code seems to have waited the maximum amount of time, as " +
            // "specified by the 'maxDownloadWaitTime' configuration parameters:\n" + msg
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // ExecutionException: An "Exception Wrapper" for internal-exceptions
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Thrown if there were any exceptions while running the 'Callable' that was created above.
        // Since the Callable's 'call()' method catches its exceptions, and wraps them inside an
        // ImageScraperException, THEORETICALLY, the 'cause'-Throwable for this 'e' should
        // **ALWAYS** be an ImageScraperException
        //
        // NOTE: If there is an ImageScraperException, make sure not to report it a second time!!!

        catch (ExecutionException e)
        {
            Throwable cause = e.getCause();

            if (ImageScraperException.class.isAssignableFrom(cause.getClass()))
                throw (ImageScraperException) cause;

            // This call either returns null, or throws an ImageScraperException 
            // Depending upon the boolean 'r.request.skipOnDownloadException'

            return r.reportEx(
                r.request.skipOnDownloadException,
                "Exception throw by Java Image-Download Code",
                "HTTP Image-Download",
                e
            );
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // InterruptedException: I THINK THIS IS UNREACHABLE - UNLESS USER IS INTERRUPTING THINGS!
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // This should mostly be unreachable, unless the end user is 'playing games' with Java's
        // Thread Mechanism.  According to the JavaDoc Pgae for 'InterruptedException' - this is
        // only thrown if the Thread is interrupte, which certainly won't happen on account of
        // anything in this tool's code!

        catch (InterruptedException e)
        {
            // This call either returns null, or throws an ImageScraperException 
            // Depending upon the boolean 'r.request.skipOnDownloadException'

            return r.reportEx(
                r.request.skipOnDownloadException,
                "Image Download Code Thread was Interrupted",
                "HTTP Image-Download",
                e
            );
        }
    }

    private static BufferedImage downloadImageCallable(RECORD r) throws ImageScraperException
    {
        BufferedImage       image   = null;
        HttpURLConnection   con     = null;
        Exception           ex      = null;

        try
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // FIRST DOWNLOAD ATTEMPT
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (r.request.alwaysUseUserAgent)
            {
                con = (HttpURLConnection) r.url.openConnection();
                con.setRequestMethod("GET");
                con.setRequestProperty("User-Agent", r.request.userAgent);

                image = ImageIO.read(con.getInputStream());
            }

            else image = ImageIO.read(r.url);


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // First Download-Attempt Was Possibly Successfull
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (image != null) return image;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // IF NULL-IMAGE && NO-RETRY: Then either return null or throw ImageScraperException
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            else if (r.request.alwaysUseUserAgent || (! r.request.retryWithUserAgent))
            {
                // This call either returns null, or throws an ImageScraperException 
                // Depending upon the boolean 'r.request.skipOnNullImageException'

                return r.reportEx(
                    r.request.skipOnNullImageException,
                    "Downloaded Empty / Null Image",
                    "HTTP Image-Download",
                    (NullImageException) new NullImageException
                        ("The Image Failed to Download Properly").fillInStackTrace()
                );
            }    
        }

        catch (ImageScraperException e) { throw e; }

        catch (Exception e) // (IOException | IIOException e)
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // EXCEPTION WAS THROWN: So **Possibly** Still need to retry with the User-Agent
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (r.request.retryWithUserAgent && (! r.request.alwaysUseUserAgent))
            {
                if (r.logLevelGTEQ2) r.appendI4(
                    "Image Download Failed - Re-attempting Download with / via User-Agent: " +
                        r.request.userAgent + '\n'
                    );
            }

            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // NO RETRY: Either Skip to next image (return null), or throw ImageScraperException
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            else
            {
                // This call either returns null, or throws an ImageScraperException 
                // Depending upon the boolean 'r.request.skipOnDownloadException'

                return r.reportEx(
                    r.request.skipOnDownloadException,
                    "Java HTTP Image Downloader javax.imageio.ImageIO.read(...) threw Exception",
                    "HTTP Image-Download",
                    e
                );
            }
        }

        try
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // SECOND DOWNLOAD ATTEMPT
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            con = (HttpURLConnection) r.url.openConnection();
            con.setRequestMethod("GET");
            con.setRequestProperty("User-Agent", r.request.userAgent);

            image = ImageIO.read(con.getInputStream());


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Second Download-Attempt Was Possibly Successfull
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (image != null) return image;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // IF NULL-IMAGE: Then either return null or throw ImageScraperException
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // This call either returns null, or throws an ImageScraperException 
            // Depending upon the boolean 'r.request.skipOnNullImageException'

            return r.reportEx(
                r.request.skipOnNullImageException,
                "Downloaded Empty / Null Image",
                "HTTP Image-Download",
                (NullImageException) new NullImageException
                    ("The Image Failed to Download Properly").fillInStackTrace()
            );
        }

        catch (ImageScraperException e) { throw e; }

        catch (Exception e)
        {
            // This call either returns null, or throws an ImageScraperException 
            // Depending upon the boolean 'r.request.skipOnNullskipOnDownloadExceptionImageException'

            return r.reportEx(
                r.request.skipOnDownloadException,
                "Java HTTP Image Downloader javax.imageio.ImageIO.read(...) threw Exception",
                "HTTP Image-Download",
                e
            );
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Convert the java.awt.image.BufferedImage **INTO** a Java byte[]-Array
    // ********************************************************************************************
    // ********************************************************************************************


    // This just converts an image in the format of a 'BufferedImage' into an image that is an
    // array of bytes.  This method will attempt to save the image using the format that was
    // extracted using the URL-Name / FileName.  If that fails, there is a for-loop that will
    // attempt to save the image using the other formats.

    private static Ret2<byte[], IF> writeBufferedImageToByteArray
        (RECORD r, BufferedImage image, IF extGuess)
        throws ImageScraperException
    {
        // This is merely an array of all available formats that may be used to save or download
        // an image.

        IF[] allFormats = IF.values();

        // This is used to generated the returned byte[] array.
        ByteArrayOutputStream baos = new ByteArrayOutputStream();

        // This is used if the image could not be converted
        Exception saveItEx = null;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // If the provided Image-Type is NON-NULL, try to save and return the Byte[]-Array
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (extGuess != null)

            try
            {
                ImageIO.write(image, extGuess.extension, baos);
                baos.flush();
                baos.close();

                if (r.logLevelEQ3) r.appendI4(
                    "Successfully Saved '." + extGuess.extension + "' URL to a '." +
                    extGuess.extension + "' Formatted Byte-Array.\n"
                );

                return new Ret2<>(baos.toByteArray(), extGuess);
            }

            catch (Exception e)
            {
                // IMPORTANT: It **IS NOT** time to quit yet!  Try the other Image-Types before
                //            reporting this as a Failed / Exception Case.

                saveItEx = e;

                if (r.logLevelEQ3) r.appendI4(
                    "Failed to Convert '." + extGuess.extension + "' URL to a '." +
                    extGuess.extension + "' Formatted Byte-Array.\n"
                );

                for (int i=0; i < allFormats.length; i++)

                    if (allFormats[i] == extGuess) { allFormats[i] = null;  break; }                
            }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Try any / all other formats that have not yet been attempted
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        for (IF format : allFormats)

            try
            {
                baos.reset();
                ImageIO.write(image, format.extension, baos);
                baos.flush();
                baos.close();

                if (r.logLevelEQ3) r.appendI4(
                    "Successfully Saved Image-URL to Byte-Array, Using as Guess '." +
                    format.extension + "' Format\n"
                );

                return new Ret2<>(baos.toByteArray(), format);
            }

            catch (Exception e)
                { if (saveItEx == null) saveItEx = e; }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // All attempts to write using a specific format have failed.  Handle the Failure.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This call either returns null, or throws an ImageScraperException 
        // Depending upon the boolean 'r.request.skipOnImageWritingFail'

        return r.reportEx(
            r.request.skipOnImageWritingFail,
            "Could not translate java.awt.image.BufferedImage to a byte[]-Array with *Any* " +
                "Standard Image-Format",
            "BufferedImage to byte[]-Array",
            saveItEx
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Write to Disk, or Send to Request.imageReceiver
    // ********************************************************************************************
    // ********************************************************************************************


    private static void handleImageByteArray(RECORD r) throws ImageScraperException
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Get the File-Name, this likely is an "error-free" step, but check just in case.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        String tempFileName = computeFileName(r);

        if (tempFileName == null) return; 

        r.imageInfo.setFileName(tempFileName);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Run the User's Keeper-Predicate, if one was supplied
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        boolean keepIt = true;

        if (r.request.keeperPredicate != null)

            try
                { keepIt = r.request.keeperPredicate.test(r.imageInfo); }

            catch (Exception e)
                { r.userLambdaEx("keeperPredicate", e);  return;}


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Write-Image, or send to Request.imageReceiver
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (! keepIt)
        {
            r.results.predicateReject(r.imageInfo);

            // Now let the user-log know... (MAYBE, IF THEY HAVE LEVEL-CLEARANCE)
            if (r.logLevelEQ3) r.appendI4("User-Provided Keeper Predicate Rejected this Image.");
            if (r.logLevelEQ1) r.append("x ");
        }

        else writeOrTransmit(r);
    }

    private static String computeFileName(RECORD r) throws ImageScraperException
    {
        String preFix = (r.request.fileNamePrefix != null) ? r.request.fileNamePrefix : "";


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Use User-Provided "Get File-Name Lambda" - 'Request.getImageFileSaveName'
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (r.request.getImageFileSaveName != null)
        {
            String file = null;

            try
                { file = r.request.getImageFileSaveName.apply(r.imageInfo); }

            catch (Exception e)
                { return r.userLambdaEx("getImageFileSaveName", e); }

            return preFix + file;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Use 'Results.successCounter' for the File-Name
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        else if (r.request.useDefaultCounterForImageFileNames)

            return preFix + r.request.counterPrinter.apply(r.results.successCounter);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Use the original URL's "File-Name" (Remember, on Yahoo! News, this don't work!)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        else
        {
            String temp = r.imageInfo.url.getFile().substring(1);

            if (r.imageInfo.guessedExtension == null) return preFix + temp;

            String ext = r.imageInfo.guessedExtension.extension;

            if (temp.toLowerCase().endsWith('.' + ext))
                return preFix + temp.substring(0, temp.length() - 1 - ext.length());

            if (r.imageInfo.guessedExtension.alternateExtension == null) return preFix + temp;

            ext = r.imageInfo.guessedExtension.alternateExtension;

            if (temp.toLowerCase().endsWith('.' + ext))
                return preFix + temp.substring(0, temp.length() - 1 - ext.length());

            throw new UnreachableError();
        }
    }

    private static void writeOrTransmit(RECORD r) throws ImageScraperException
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Case: ImageReceiver
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (r.request.imageReceiver != null)

            try 
            {
                r.request.imageReceiver.accept(r.imageInfo);
                r.results.success(r.imageInfo, null /* no target directory */);

                if (r.logLevelEQ1) r.append("✓ ");

                else if (r.logLevelGTEQ2)
                    r.appendI4("Image Properly Transmitted to Request.imageReceiver\n");

                return;
            }

            catch (Exception e)
                { r.userLambdaEx("imageReceiver", e);  return; }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Case: File-System
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        String dirName = null;

        if (r.request.targetDirectory != null) dirName = r.request.targetDirectory;

        else if (r.request.targetDirectoryRetriever != null)
        {
            File dir;


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Run the Request.targetDirectoryRetriever instance
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            try 
                { dir = r.request.targetDirectoryRetriever.apply(r.imageInfo); }

            catch (Exception e)
                { r.userLambdaEx("targetDirectoryRetriever", e);  return; }


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Check that the directory returned is non-null and writeable
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            try
                { WritableDirectoryException.check(dir); }

            catch (Exception e)
            {
                // This call either returns null, or throws an ImageScraperException 
                // Depending upon the boolean 'r.request.skipOnImageWritingFail'
        
                r.reportEx(
                    r.request.skipOnImageWritingFail,
                    "Target-Directory reference provided is not a File-System Writeable Directory",
                    "Write Image to Disk",
                    e
                );
            }
        }

        // This scenario is checked inside the Request class "check" method
        else throw new UnreachableError();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // WRITE THE FILE
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (! dirName.endsWith(File.separator)) dirName = dirName + File.separator;

        try
        {
            String saveName =
                dirName + r.imageInfo.fileName() + '.' + r.imageInfo.actualExtension.extension;

            FileRW.writeBinary(r.imageInfo.imgByteArr, saveName);
            r.results.success(r.imageInfo, dirName);

            if (r.logLevelEQ1) r.append("✓ ");

            else if (r.logLevelGTEQ2)
                r.appendI4("Image saved successfully to: [" + saveName + "]\n");
        }

        catch (Exception e)
        {
            // This call either returns null, or throws an ImageScraperException 
            // Depending upon the boolean 'r.request.skipOnImageWritingFail'
    
            r.reportEx(
                r.request.skipOnImageWritingFail,
                "Exception thrown while attempting to write an image file to disk.",
                "Write Image to Disk",
                e
            );
        }
    }
}