package Torello.HTML.Tools.Images;

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

import Torello.Java.Additional.Ret2;

import java.util.function.*;

import java.io.Serializable;
import java.io.File;
import java.net.URL;
import java.net.MalformedURLException;
import java.util.Vector;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import java.util.regex.Matcher;


/**
 * Holds all relevant configurations and parameters needed to run the primary download-loop of
 * class {@link ImageScraper}
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST>
 * <EMBED CLASS='external-html' DATA-FILE-ID=REQ_STR_BUILDER1_EX>
 */
@SuppressWarnings("overrides")
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="IMAGE_SCRAPER_CLASS")
public class Request implements Cloneable, Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // MAIN CONSTRUCTORS
    // ********************************************************************************************
    // ********************************************************************************************


    // There are 5 or 6 'static' builder-methods below.  The only reason on earth that those are
    // static-methods rather than constructors is that their parameter lists all use the same
    // 'Iterable', but with a different Generic-Parameter.  If you convert those to Constructors,
    // you will get that they have the "Same Erasure", and that compiling cannot continue.
    //
    // Instead they are methods that have slightly different names, and the Java-Compiler, instead,
    // shuts up, and stops complaining.

    private Request(
            Vector<URL> source, int size, URL originalPageURL, Vector<String[]> b64Images,
            Vector<Exception> tagNodeSRCExceptions
        )
    {
        this.source                 = source;
        this.size                   = size;
        this.counterPrinter         = getPrinter(size);
        this.originalPageURL        = originalPageURL;
        this.b64Images              = b64Images;
        this.tagNodeSRCExceptions   = tagNodeSRCExceptions;
    }

    private Request(Vector<URL> source, int size, URL originalPageURL)
    {
        this.source                 = source;
        this.size                   = size;
        this.counterPrinter         = getPrinter(size);
        this.originalPageURL        = originalPageURL;
        this.b64Images              = null;
        this.tagNodeSRCExceptions   = null;
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Small static constructor-helper
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    private static IntFunction<String> getPrinter(int size)
    {
        // Now produce the Printer for the Image-Number.  All this does is make sure to do an
        // appropriate zero-padding for the text-output.

        if      (size < 10)     return (int i) -> "" + i;
        else if (size < 100)    return StringParse::zeroPad10e2;
        else if (size < 1000)   return StringParse::zeroPad;
        else if (size < 10000)  return StringParse::zeroPad10e4;

        // This case seems extremely unlikely and even largely preposterous, but leaving it like
        // this means I will never have to analyze this crap ever again.  Note that the above case
        // where size is greater than 1,000 seems a little ridiculous.  Usually there are under 100
        // photos on any one HTML Page.

        else
        {
            final int power = (int) Math.floor(Math.log10(size));
            return (int i) -> StringParse.zeroPad(i, power);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Constructor-Like Builder Methods (Cannot Use Constructors because of "Erasure")
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Builds an instance of this class from a list of {@code URL's} as {@code String's}
     * 
     * @param source <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ITER_STR>
     * 
     * @return A {@code 'Request'} instance.  This may be further configured by assigning values to
     * any / all fields (which will still have their initialized / default-values)
     * 
     * @throws NullPointerException If any of the {@code String's} in the {@code Iterable} are null
     * 
     * @throws IllegalArgumentException If any of the {@code URL's} are {@code String's} which
     * begin with neither {@code 'http://'} nor {@code 'https://'}.  Since this method doesn't
     * accept the parameter {@code 'originalPageURL'}, each and every {@code URL} in the 
     * {@code 'source'} iterable must be a full &amp; complete {@code URL}.
     * 
     * <BR /><BR />This exception will also throw if there are any {@code URL's} in the
     * {@code String}-List that cause a {@code MalformedURLException} to throw when constructing an
     * instance of {@code java.net.URL} from the {@code String}.  In these cases, the original
     * {@code MalformedURLException} will be assigned to the {@code 'cause'}, and may be retrieved
     * using the exception's {@code getCause()} method.
     */
    public static Request buildFromStrIter(Iterable<String> source)
    {
        Vector<URL> temp    = new Vector<>();
        int         count   = 0;

        for (String urlStr : source)
        {
            count++;

            if (urlStr == null) throw new NullPointerException(
                "The " + count + StringParse.ordinalIndicator(count) + "th element of " +
                "Iterable-Parameter 'source' is null"
            );

            if (StrCmpr.startsWithNAND(urlStr, "http://", "https://"))

                throw new IllegalArgumentException(
                    "The " + count + StringParse.ordinalIndicator(count) + "th element of " +
                    "Iterable-Parameter 'source' did neither begin with 'http://' nor " +
                    "'https://'.  If there are any partial URL's in you Iterable, you must " +
                    "re-build using an 'originalPageURL' parameter in order to resolve any and " +
                    "all partial URL's."
                );

            try
                { temp.add(new URL(urlStr)); }

            catch (MalformedURLException e)
            {
                throw new IllegalArgumentException(
                    "When attempting to build the " + count + StringParse.ordinalIndicator(count) +
                    " element of Iterable-Parameter 'source', a MalformedURLException threw.  " +
                    "Please see e.getCause() for details.",
                    e
                );
            }
        }

        return new Request(temp, count, null);
    }

    /**
     * Builds an instance of this class from a list of {@code URL's} as {@code String's}
     * 
     * @param source <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ITER_STR>
     * @param originalPageURL <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ORIG_PG_URL>
     * 
     * @param skipDontThrowIfBadStr If an exception is thrown when attempting to resolve a
     * partial-{@code URL}, and this parameter is {@code TRUE}, then that exception is suppressed
     * and logged, and the builder-loop continues to the next {@code URL}-as-a-{@code String}.
     * 
     * <BR /><BR />When this parameter is passed {@code FALSE}, unresolvable {@code URL's} will
     * generate an {@code IllegalArgumentException}-throw.
     * 
     * <BR /><BR />Note that the presence of a null in the {@code Iterable 'source'} parameter
     * will always force this method to throw {@code NullPointerException}.
     * 
     * @return A {@code 'Request'} instance.  This may be further configured by assigning values to
     * any / all fields (which will still have their initialized / default-values)
     * 
     * @throws NullPointerException If any of the {@code String's} in the {@code Iterable} are null
     * 
     * @throws IllegalArgumentException This exception will also throw if there are any
     * {@code URL's} in the {@code String}-List that cause a {@code MalformedURLException} to throw
     * when constructing an instance of {@code java.net.URL} from the {@code String}.  In these
     * cases, the generated {@code MalformedURLException} will be assigned to the exception's
     * {@code 'cause'}, and may therefore be retrieved using this exception's {@code getCause()}
     * method.
     */
    public static Request buildFromStrIter
        (Iterable<String> source, URL originalPageURL, boolean skipDontThrowIfBadStr)
    {
        if (originalPageURL == null) throw new NullPointerException("'originalPageURL' is null.");

        Vector<URL>         temp            = new Vector<>();
        Vector<Exception>   strExceptions   = new Vector<>();
        Vector<String[]>    b64Dummy        = new Vector<>();
        int                 count           = 0;

        for (String urlStr : source)
        {
            count++;

            // This isn't used here, but the (private) Request-Constructor needs an empty Vector if
            // there aren't any b64-Images.

            b64Dummy.add(null);

            if (urlStr == null) throw new NullPointerException(
                "The " + count + StringParse.ordinalIndicator(count) + " element of " +
                "Iterable-Parameter 'source' is null"
            );

            Ret2<URL, MalformedURLException> r2 = Links.resolve_KE(urlStr, originalPageURL);

            if (r2.b == null) temp.add(r2.a);
            
            else
            {
                if (skipDontThrowIfBadStr)
                {
                    temp.add(null);
                    strExceptions.add(r2.b);
                }

                else throw new IllegalArgumentException(
                    "When attempting to resolve the " + count +
                    StringParse.ordinalIndicator(count) + " TagNode of Iterable-Parameter " +
                    "'source' an Exception was thrown.  See 'getCause' for details.",
                    r2.b
                );
            }

        }

        return new Request(temp, count, originalPageURL, b64Dummy, strExceptions);
    }

    /**
     * Builds an instance of this class using the {@code SRC}-Attribute from a list of
     * {@link TagNode}'s.
     * 
     * @param source <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ITER_TGND>
     * 
     * @param originalPageURL <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ORIG_PG_URL>
     *
     * @param skipDontThrowIfBadSRCAttr
     * <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_SKIP_BOOL>
     * 
     * @return A {@code 'Request'} instance.  This may be further configured by assigning values to
     * any / all fields (which will still have their initialized / default-values)
     * 
     * @throws NullPointerException If any of the {@link TagNode}'s in the {@code Iterable} are
     * null
     * 
     * @throws SRCException If any of the {@link TagNode}'s in the list do not have a {@code 'SRC'}
     * Attribute, and {@code 'skipDontThrowIfBadSRCAttr'} is {@code FALSE}.
     * 
     * <BR /><BR />This exception will also throw if there are any {@code URL's} in the
     * {@link TagNode}-List that cause a {@code MalformedURLException} to throw when constructing
     * an instance of {@code java.net.URL} (from the {@code TagNode's SRC}-Attribute).  In these
     * cases, the generated {@code MalformedURLException} will be assigned to the exception's
     * {@code 'cause'}, and may therefore be retrieved using the exception's {@code getCause()}
     * method.
     *
     * <BR /><BR />If {@code 'skipDontThrowIfBadSRCAttr'} is {@code FALSE}, then this
     * exception will not throw, and a null will be placed in the query-list.
     */
    public static Request buildFromTagNodeIter
        (Iterable<TagNode> source, URL originalPageURL, boolean skipDontThrowIfBadSRCAttr)
    {
        if (originalPageURL == null) throw new NullPointerException("'originalPageURL' is null.");

        Vector<URL>         temp                    = new Vector<>();
        int                 count                   = 0;
        Vector<String[]>    b64Images               = new Vector<>();
        Vector<Exception>   tagNodeSRCExceptions    = new Vector<>();

        for (TagNode tn : source)
        {
            count++;

            if (tn == null) throw new NullPointerException(
                "The " + count + StringParse.ordinalIndicator(count) + " element of " +
                "Iterable-Parameter 'source' is null"
            );

            String urlStr = tn.AV("src");

            if (urlStr == null)
            {
                SRCException e = new SRCException(
                    "The " + count + StringParse.ordinalIndicator(count) + " TagNode of " +
                    "Iterable-Parameter 'source' does not have a SRC-Attribute"
                );

                if (skipDontThrowIfBadSRCAttr)
                {
                    temp.add(null);
                    b64Images.add(null);
                    tagNodeSRCExceptions.add(e);
                    continue;
                }

                else throw e;
            }


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Handle the Base-64 Stuff, here.  08.31.2023
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            Matcher m = IF.B64_INIT_STRING.matcher(urlStr);

            if (m.find())
            {
                temp.add(null);

                b64Images.add(new String[] { m.group(1), m.group(2)});

                continue;
            }


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Handle a normal URL.  08.31.2023
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            Ret2<URL, MalformedURLException> r2 = Links.resolve_KE(urlStr, originalPageURL);

            if (r2.b != null)
            {
                SRCException e = new SRCException(
                    "Attempting to resolve the " + count + StringParse.ordinalIndicator(count) +
                    " TagNode of Iterable-Parameter 'source' there was an Exception.  See " +
                    "'getCause' for details.",
                    r2.b
                );

                if (skipDontThrowIfBadSRCAttr)
                {
                    temp.add(null);
                    b64Images.add(null);
                    tagNodeSRCExceptions.add(e);
                    continue;
                }

                else throw e;
            }

            temp.add(r2.a);
        }

        return new Request(temp, count, originalPageURL, b64Images, tagNodeSRCExceptions);
    }

    /**
     * Builds an instance of this class using the {@code SRC}-Attribute from a list of
     * {@link TagNode}'s.
     * 
     * @param source <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ITER_TGND>
     *
     * @param skipDontThrowIfBadSRCAttr
     * <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_SKIP_BOOL>
     * 
     * @return A {@code 'Request'} instance.  This may be further configured by assigning values to
     * any / all fields (which will still have their initialized / default-values)
     * 
     * @throws NullPointerException If any of the {@link TagNode}'s in the {@code Iterable} are
     * null
     * 
     * @throws SRCException If any of the {@link TagNode}'s in the list do not have a
     * {@code 'SRC'}-Attribute, and {@code 'skipDontThrowIfBadSRCAttr'} is {@code FALSE}.
     * 
     * <BR /><BR />This exception will also throw if any of the {@code URL's} assigned to a
     * {@code 'SRC'}-Attribute are partial-{@code URL's} which do not begin with {@code 'http://'}
     * (or {@code 'https://'}), and {@code 'skipDontThrowIfBadSRCAttr'} is {@code FALSE}.
     * 
     * <BR /><BR />Finally, if any of the {@code URL's} inside a {@link TagNode}'s'
     * {@code 'SRC'}-Attribute cause a {@code MalformedURLException}, that exception will be
     * assigned to the {@code cause} of a {@link SRCException}, and thrown (unless
     * {@code 'skipDontThrowIfBadSRCAttr'} is {@code FALSE}).
     */
    public static Request buildFromTagNodeIter
        (Iterable<TagNode> source, boolean skipDontThrowIfBadSRCAttr)
    {
        Vector<URL>         temp                    = new Vector<>();
        int                 count                   = 0;
        Vector<String[]>    b64Images               = new Vector<>();
        Vector<Exception>   tagNodeSRCExceptions    = new Vector<>();

        for (TagNode tn : source)
        {
            count++;

            if (tn == null) throw new NullPointerException(
                "The " + count + StringParse.ordinalIndicator(count) + " element of " +
                "Iterable-Parameter 'source' is null"
            );

            String urlStr = tn.AV("src");

            if (urlStr == null)
            {
                SRCException e = new SRCException(
                    "The " + count + StringParse.ordinalIndicator(count) + " TagNode of " +
                    "Iterable-Parameter 'source' does not have a SRC-Attribute"
                );

                if (skipDontThrowIfBadSRCAttr)
                {
                    temp.add(null);
                    b64Images.add(null);
                    tagNodeSRCExceptions.add(e);
                    continue;
                }

                else throw e;
            }


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Handle the Base-64 Stuff, here.  08.31.2023
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            Matcher m = IF.B64_INIT_STRING.matcher(urlStr);

            if (m.find())
            {
                temp.add(null);

                b64Images.add(new String[] { m.group(1), m.group(2)});

                continue;
            }


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Handle the Base-64 Stuff, here.  08.31.2023
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (StrCmpr.startsWithNAND(urlStr, "http://", "https://"))
            {
                SRCException e = new SRCException(
                    "The " + count + StringParse.ordinalIndicator(count) + " TagNode of " +
                    "Iterable-Parameter 'source' did neither begin with 'http://' nor " +
                    "'https://'.  Please build using an 'originalPageURL' parameter to resolve " +
                    "any and all partial URL's."
                );

                if (skipDontThrowIfBadSRCAttr)
                {
                    temp.add(null);
                    b64Images.add(null);
                    tagNodeSRCExceptions.add(e);
                    continue;
                }

                else throw e;
            }

            try
                { temp.add(new URL(urlStr)); }

            catch (MalformedURLException e)
            {
                // variable 'e' has already been defined above, use 'e2'
                SRCException e2 = new SRCException(
                    "When attempting to build the " + count + StringParse.ordinalIndicator(count) +
                    " element of Iterable-Parameter 'source', a MalformedURLException threw.  " +
                    "Please see getCause for details.",
                    e
                );

                if (skipDontThrowIfBadSRCAttr)
                {
                    temp.add(null);
                    b64Images.add(null);
                    tagNodeSRCExceptions.add(e2);
                    continue;
                }

                else throw e2;
            }
        }

        return new Request(temp, count, null, b64Images, tagNodeSRCExceptions);
    }

    /**
     * Builds an instance of this class using a list of <I><B STYLE='color: red;'>already
     * prepared</B></I> {@code URL's}.
     * 
     * @param source <EMBED CLASS='external-html' DATA-FILE-ID=REQUEST_ITER_URL>
     * 
     * @return A {@code 'Request'} instance.  This may be further configured by assigning values to
     * any / all fields (which will still have their initialized / default-values)
     * 
     * @throws NullPointerException If any of the {@code URL's} in the {@code Iterable} are null
     */
    public static Request buildFromURLIter(Iterable<URL> source)
    {
        Vector<URL> temp    = new Vector<>();
        int         count   = 0;

        for (URL url : source)
        {
            count++;

            if (url == null) throw new NullPointerException(
                "The " + count + StringParse.ordinalIndicator(count) + " element of " +
                "Iterable-Parameter 'source' is null"
            );

            temp.add(url);
        }

        return new Request(temp, count, null);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Visible Utility Methods for ImageScraper, Set by the Constructor.
    // ********************************************************************************************
    // ********************************************************************************************


    // Package-Visibility: Used only in class ImageScraper (to retrieve the Iterable)
    Iterable<URL> source() { return source; }

    // This Vector-Index Counter is used only once - three lines below
    private int b64Pos = 0;

    // Package-Visibility: Used only in class Imagescraper (to retrieve a B64-Image String-Array)
    String[] nextB64Image()
    {
        // Since the creation/construction of these Vectors is completely controlled, they should
        // never be a source of NullPointerException.  If for some odd reason they are, it is
        // better to keep a record indicating that "this really shouldn't have happened"
        //
        // These are "assert" statements.  There is no reason this method should ever be called
        // if these are null.  In the static-builder, if a null-URL is put into the source-vector
        // then one of these would be called (b64Images and/or tagNodeSRCExceptions).  In such
        // cases, both of these secondary vectors would already have references put into them.
        //
        // Since the "ImageScraper" is heavy-user-interaction class, the paranoia is 10x worse.
        // This sort of helps mitigate it, although it seems completely superfluous and unnecessary

        if (b64Images == null)          throw new UnreachableError();
        if (b64Pos >= b64Images.size()) throw new UnreachableError();

        return b64Images.elementAt(b64Pos++);
    }

    // This Vector-Index Counter is used only once - three lines below
    private int tnExPos = 0;

    // Package-Visibility: Used only by class ImageScraper
    Exception nextTNSRCException()
    {
        // Since the creation/construction of these Vectors is completely controlled, they should
        // never be a source of NullPointerException.  If for some odd reason they are, it is
        // better to keep a record indicating that "this really shouldn't have happened"
        //
        // These are "assert" statements.  There is no reason this method should ever be called
        // if these are null.  In the static-builder, if a null-URL is put into the source-vector
        // then one of these would be called (b64Images and/or tagNodeSRCExceptions).  In such
        // cases, both of these secondary vectors would already have references put into them.
        //
        // Since the "ImageScraper" is heavy-user-interaction class, the paranoia is 10x worse.
        // This sort of helps mitigate it, although it seems completely superfluous and unnecessary

        if (tagNodeSRCExceptions == null)           throw new UnreachableError();
        if (tnExPos >= tagNodeSRCExceptions.size()) throw new UnreachableError();

        return tagNodeSRCExceptions.elementAt(tnExPos++);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Primary Request Fields
    // ********************************************************************************************
    // ********************************************************************************************
 

    /** {@code URL} from whence this page has been downloaded */
    public final URL originalPageURL;

    // The Source Iterable
    private final Iterable<URL> source;

    /** The number of Image-{@code URL's} identified inside the {@code 'source'} Iterable. */
    public final int size;    

    // This is just a zero-padding printer.  It adjusts for the number of elements in the original
    // input Iterable.  If there are, for example, under 100 elements, then the first 10 elements
    // will be padded with a zero.

    final IntFunction<String> counterPrinter;

    // Any & all Base-64 Images.  This is usually empty, so it is initialized to null
    private final Vector<String[]> b64Images;

    // If the user has built from an Iterable<TagNode>, and requested to suppress-exceptions, then
    // this vector will save those exceptions so that they are ready for the return/result object.

    private final Vector<Exception> tagNodeSRCExceptions;


    // ********************************************************************************************
    // ********************************************************************************************
    // Verbosity & URL-PreProcessor
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Allows a user of this utility to specify how the <B STYLE='color: red;'>Level of
     * Verbosity</B> (or silence) is applied to the output mechanism while the tool is running.
     * 
     * <BR /><BR />Note that the Java {@code enum} {@link Verbosity} provides four distint levels,
     * and that the class {@link ImageScraper} does indeed implement all four variants of textual
     * output.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>{@code NullPointerException}:</B>
     * 
     * <BR />This field <I><B>may not be null</B></I>, or a {@code NullPointerException}: will
     * throw!
     */
    public Verbosity verbosity = Verbosity.Normal;

    /**
     * When non-null, this allows a user to modify any image-{@code URL} immediately-prior to
     * the {@link ImageScraper} beginning the download process for that image.  This is likely of
     * limited use, but there are certainly situations where (for example) escaped-characters need
     * to be un-escaped prior to starting the download system.
     * 
     * <BR /><BR />In such cases, just write a lambda-target that accepts a {@code URL}, and
     * processes it (in some way, of your chossing), and the downloader will use that updated
     * {@code URL}-instance for making the HTTP-Connection to download the picture.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public Function<URL, URL> urlPreProcessor = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // Location-Decisions for Saving an Image File (or sending to an 'imageReceiver')
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Allows a user to specify where to save an Image-File after being downloaded.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public Function<ImageInfo, File> targetDirectoryRetriever = null;

    /**
     * A functional-interface that allows a user to save an image-file to a location of his or her
     * choosing.  Implement this class if saving image files to a target-directory on the
     * file-system is not acceptable, and the programmer wishes to do something else with the
     * downloaded images.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public Consumer<ImageInfo> imageReceiver = null;

    /**
     * When this configuration-field is non-null, this {@code String} parameter is used to 
     * identify the file-system directory to where downloaded image-files are to be saved.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public String targetDirectory = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // File-Name given to an Image File
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * When this field is non-null, this {@code String} will be <I>prepended</I> to each image
     * file-name that is saved or stored to the file-system.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public String fileNamePrefix = null;

    /**
     * When true, images will be saved according to a counter; when this is {@code FALSE}, the
     * software will attempt to save these images using their original filenames - picked from
     * the <B>URL</B>.  Saving using a counter is the default behaviour for this class.
     */
    public boolean useDefaultCounterForImageFileNames = true;

    /**
     * When this field is non-null, each time an image is written to the file-system, this function
     * will be queried for a file-name before writing the the image-file.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public Function<ImageInfo, String> getImageFileSaveName = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // BOOLEANS'S: Continuing or Throwing on Failure & Exception
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Requests that the downloader-logic catch any &amp; all exceptions that are thrown when
     * downloading images from an Internet-{@code URL}.  The failed download is simply reflected in
     * the {@link Results} output arrays, and the download-process moves onto the next
     * {@code Iterable}-Element.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Exception's Skipped:</B>
     * 
     * <BR />This particular configuration-{@code boolean} allows a user to focus on exceptions
     * that are thrown while Java's {@code ImageIO} class is downloading and image, and suddenly
     * fails.
     */
    public boolean skipOnDownloadException = false;

    /**
     * Requests that the downloader-logic catch any &amp; all exceptions that are thrown when
     * decoding Base-64 Encoded Images.  The failed conversion is simply reflected in the 
     * {@link Results} output arrays, and the download-process moves onto the next
     * {@code Iterable}-Element.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Exception's Skipped:</B>
     * 
     * <BR />This particular configuration-{@code boolean} allows a user to focus on exceptions
     * that are thrown when Java's Base-64 Image-Decoder throws an exception.
     */
    public boolean skipOnB64DecodeException = false;

    /**
     * Requests that the downloader-logic catch any &amp; all exceptions that are thrown while
     * waiting for an image to finish downloading from an Internet-{@code URL}.  The failed
     * download is simply reflected in the {@link Results} output arrays, and the download-process
     * moves onto the next {@code Iterable}-Element.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Exception's Skipped:</B>
     * 
     * <BR />This particular configuration-{@code boolean} allows a user to focus on exceptions
     * that are thrown when the Monitor-Thread has timed-out.
     */
    public boolean skipOnTimeOutException = false;

    /**
     * There are occasions when Java's {@code ImageIO} class returns a null image, rather than
     * throwing an exception at all.  In these cases, the {@link ImageScraper} class throws its own
     * exception - unless this {@code boolean} has expressly requested to skip-and-move-on when the
     * {@code ImageIO} returns null from downloading a {@code URL}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Exception's Skipped:</B>
     * 
     * <BR />This particular configuration-{@code boolean} allows a user to focus on exceptions
     * that are thrown by the {@link ImageScraper} when a downloaded image is null.
     */
    public boolean skipOnNullImageException = false;

    /**
     * If an attempt is made to write an Image to the File-System, and an exception is thrown, this
     * boolean requests that rather than throwing the exception, the downloader make a note in the
     * log that a failure occured, and move on to the next image.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Exception's Skipped:</B>
     * 
     * <BR />This particular configuration-{@code boolean} allows a user to focus on exceptions
     * that are thrown when writing an already downloaded and converted image to the file-system.
     */
    public boolean skipOnImageWritingFail = false;

    /**
     * This can be helpful if there are any "doubts" about the quality of the Functional-Interfaces
     * that have been provided to this {@code Request}-instance.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Exception's Skipped:</B>
     * 
     * <BR />This particular configuration-{@code boolean} allows a user to focus on exceptions
     * that are thrown by any of the Lambda-Target / Functional-Interfaces that are provided by the
     * user via this {@code Request}-instance.
     */
    public boolean skipOnUserLambdaException = false;


    // ********************************************************************************************
    // ********************************************************************************************
    // USER-PREDICATE'S & BOOLEAN'S: Which Image Files to Save, and Which to Skip
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If this field is non-null, then before any {@code URL} is connected for a download, the
     * downloaded mechanism will ask this {@code URL-Predicate} for permission first.  If this
     * {@code Predicate} returns {@code FALSE} for a given {@code URL}, then that image will not be
     * downloaded, but rather skipped, instead.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Setting to null:</B>
     * 
     * <BR />This field may be null, and when it is, it shall be ignored.  Upon construction, this
     * class initializes this field to null.
     */
    public Predicate<URL> skipURL = null;

    /**
     * This scraper has the ability to decode and save {@code Base-64} Images, and they may be
     * downloaded or skipped - <I>based on this {@code boolean}</I>.  If an
     * {@code Iterable<TagNode>} is passed to the constructor, and one of those
     * {@code TagNode's} contain an Image Element
     * ({@code <IMG SRC="data:image/jpeg;base64,...data">}) this class has the ability to
     * interpret and save the image to a regular image file.  By default, {@code Base-64}
     * images are skipped, but they can also be downloaded as well.
     */
    public boolean skipBase64EncodedImages = false;

    /**
     * Allows for a user-provided decision-predicate about whether to retain &amp; save, or
     * discard, an image after downloading.  All information available in data-flow class
     * {@link ImageInfo} is provided to this predicate, and ought to be enough to decide whether
     * or not to save or reject any of the downloaded image.
     */
    public Predicate<ImageInfo> keeperPredicate = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // Avoiding Hangs and Locks with a TimeOut
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is the default maximum wait time for an image to download ({@value}).  This value may
     * be reset or modified by instantiating a {@code ImageScraper.AdditionalParameters} class, and
     * passing the desired values to the constructor.  This value is measured in units of
     * {@code public static final java.util.concurrent.TimeUnit MAX_WAIT_TIME_UNIT}
     *
     * @see #MAX_WAIT_TIME_UNIT
     * @see #maxDownloadWaitTime
     */
    public static final long MAX_WAIT_TIME = 10;

    /**
     * This is the default measuring unit for the {@code static final long MAX_WAIT_TIME} member.
     * This value may be reset or modified by instantiating a 
     * {@code ImageScraper.AdditionalParameters} class, and passing the desired values to the
     * constructor.
     *
     * @see #MAX_WAIT_TIME
     * @see #waitTimeUnits
     */
    public static final TimeUnit MAX_WAIT_TIME_UNIT = TimeUnit.SECONDS;

    /**
     * If you do not want the downloader to hang on an image, which is sometimes an issue
     * depending upon the site from which you are making a request, set this parameter, and the
     * downloader will not wait past that amount of time to download an image.  The default
     * value for this parameter is {@code 10 seconds}.  If you do not wish to set the
     * max-wait-time "the download time-out" counter, then leave the parameter
     * {@code "waitTimeUnits"} set to {@code null}, and this parameter will be ignored.
     */
    public long maxDownloadWaitTime = MAX_WAIT_TIME;

    /**
     * This is the "unit of measurement" for the field {@code long maxDownloadWaitTime}.
     * <BR /><BR /><B>NOTE:</B> <I>This parameter may be {@code null}, and if it is
     * <SPAN STYLE="color: red;"> both <B>this</B> parameter and the parameter <B>{@code long
     * maxDownloadWaitTime}</B> will be ignored</SPAN></I>, and the default maximum-wait-time
     * (download time-out settings) will be used instead.
     *
     * <BR /><BR /><B>READ:</B> java.util.concurrent.*; package, and about the {@code class
     * java.util.concurrent.TimeUnit} for more information.
     */
    public TimeUnit waitTimeUnits = MAX_WAIT_TIME_UNIT;


    // ********************************************************************************************
    // ********************************************************************************************
    // USER AGENT
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * There are web-sites that expect a <B STYLE='color: red;'>User-Agent</B> to be defined before
     * allowing an image download to progress.  There are even web-sites and servers that simply
     * will not connect to a scraper unless a User-Agent is defined.
     * 
     * <BR /><BR />This is the default <B STYLE='color: red;'>User-Agent</B> that is defined inside
     * of class {@link Scrape}.
     * 
     * @see Scrape#USER_AGENT;
     */
    public static final String DEFAULT_USER_AGENT = Scrape.USER_AGENT;

    /**
     * This 
     */
    public String userAgent = DEFAULT_USER_AGENT;

    public boolean alwaysUseUserAgent = false;

    public boolean retryWithUserAgent = true;


    // ********************************************************************************************
    // ********************************************************************************************
    // Check for Validity Method
    // ********************************************************************************************
    // ********************************************************************************************


    void CHECK()
    {
        // This is the same as an assert-statement
        if (source == null) throw new UnreachableError();

        if (verbosity == null) throw new NullPointerException(
            "Verbosity has been set to null.  It is initialized to Verbosity.Normal.  Any level " +
            "may be chosen, but null is not allowed here."
        );
        
        if (maxDownloadWaitTime < 0) throw new IllegalArgumentException(
            "You have passed a negative number for parameter maxDownloadWaitTime, and this is " +
            "not allowed here."
        );

        if (waitTimeUnits == null) throw new NullPointerException
            ("Field 'waitTimeUnits' is null");

        int count =
            ((targetDirectory == null) ? 0 : 1) +
            ((imageReceiver == null) ? 0 : 1) +
            ((targetDirectoryRetriever == null) ? 0 : 1);

        if (count != 1) throw new IllegalArgumentException(
            "Of the three Save-Specifiers: targetDirectory, imageReceiver and " +
            "targetDirectoryRetriever, precisely one of them must be non-null.  Upon completion " +
            "of the class 'Request' Constructor, there are [" + count + "] which are non-null.  " +
            "This is not allowed."
        );

        if (targetDirectory != null)
        {
            // Ensures that the target directory exists, and is writable
            WritableDirectoryException.check(targetDirectory);

            // Makes sure that the directory ends with a slash / file-separator.
            if (! targetDirectory.endsWith(File.separator)) if (targetDirectory.length() > 0)
                targetDirectory = targetDirectory + File.separator;
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // TURN ON **ALL** Exception-Skip Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This allows a user to quickly / easily set all {@code 'skipOn'} flags in one method call.
     */
    public void skipOnAllExceptions()
    {
        // exceptions thrown by Java's ImageIO class when downloading and image
        skipOnDownloadException =

            // if Java's Base-64 Image-Decoder throws an exception.
            skipOnB64DecodeException =

            // exception that's thrown when the Monitor-Thread has timed-out.
            skipOnTimeOutException =

            // exception that's thrown when a downloaded image is null.
            skipOnNullImageException =

            // exceptions thrown when writing an already downloaded image to the file-system.
            skipOnImageWritingFail =

            // exceptions thrown by any of the User-Provided Lambda-Target / Functional-Interfaces
            skipOnUserLambdaException = true;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Standard-Java Object Methods
    // ********************************************************************************************
    // ********************************************************************************************


    private String OBJ_TO_CLASS_NAME(Object o)
    {
        if (o == null) return "null\n";

        Class<?> c = o.getClass();

        return c.isAnonymousClass() ? "Anonymous Class\n" : (c.getName() + '\n');
    }

    private static final String I4 = "    ";

    /**
     * Converts {@code 'this'} instance into a simple Java-{@code String}
     * @return A {@code String} where each field has had a 'best efforts' {@code String}-Conversion
     */
    public String toString()
    {
        return
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Primary Request Fields
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "Primary Request Fields:\n" +

            // public final URL originalPageURL;
            I4 + "originalPageURL:                     " + this.originalPageURL + '\n' +

            // private final int size;
            I4 + "size:                                " + this.size + '\n' +

            // public Verbosity = Verbosity.Normal;
            I4 + "Verbosity:                           " + this.verbosity + '\n' +

            '\n' +


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Location-Decisions for Saving an Image File
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "Location-Decisions for Saving an Image File:\n" +

            // public Function<ImageInfo, File> targetDirectoryRetriever = null;
            I4 + "targetDirectoryRetriever:            " +
                OBJ_TO_CLASS_NAME(this.targetDirectoryRetriever) +

            // public Consumer<ImageInfo> imageReceiver = null;
            I4 + "imageReceiver:                       " + OBJ_TO_CLASS_NAME(this.imageReceiver) +

            // public String targetDirectory = null;
            I4 + "targetDirectory:                     " + ((this.targetDirectory != null)
                ? ("[\"" + this.targetDirectory + "\"]") : "null") + '\n' +

            '\n' +


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // File-Name given to an Image File
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "File-Name given to an Image File:\n" +

            // public String fileNamePrefix = null;
            I4 + "fileNamePrefix:                      " + ((this.fileNamePrefix != null)
                ? ("[\"" + this.fileNamePrefix + "\"]") : "null") + '\n' +

            // public boolean useDefaultCounterForImageFileNames = true;
            I4 + "useDefaultCounterForImageFileNames:  " +
                this.useDefaultCounterForImageFileNames + '\n' +

            // public Function<ImageInfo, String> getImageFileSaveName = null;
            I4 + "getImageFileSaveName:                " +
                OBJ_TO_CLASS_NAME(this.getImageFileSaveName) + '\n' +

            '\n' +


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // BOOLEAN'S: Continuing or Throwing on Failure & Exception
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "Boolean-Flags: Continuing or Throwing on Failure & Exception:\n" +

            // public boolean skipOnDownloadException = false;
            I4 + "skipOnDownloadException:             " + this.skipOnDownloadException + '\n' +

            // public boolean skipOnB64DecodeException = false;
            I4 + "skipOnB64DecodeException:            " + this.skipOnB64DecodeException + '\n' +

            // public boolean skipOnTimeOutException = false;
            I4 + "skipOnTimeOutException:              " + this.skipOnTimeOutException + '\n' +

            // public boolean skipOnNullImageException = false;
            I4 + "skipOnNullImageException:            " + this.skipOnNullImageException + '\n' +

            // public boolean skipOnImageWritingFail = false;
            I4 + "skipOnImageWritingFail:              " + this.skipOnImageWritingFail + '\n' +

            // public boolean skipOnUserLambdaException = false;
            I4 + "skipOnUserLambdaException:           " + this.skipOnUserLambdaException + '\n' +

            '\n' +


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // USER-PREDICATE'S & BOOLEAN'S: Which Image Files to Save, and Which to Skip
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "User-Predicate's: Which Image-Files to Save, and Which to Skip:\n" +

            // public Predicate<URL> skipURL = null;
            I4 + "skipURL:                             " + OBJ_TO_CLASS_NAME(this.skipURL) +

            // public boolean skipBase64EncodedImages = false;
            I4 + "skipBase64EncodedImages:             " + this.skipBase64EncodedImages + '\n' +

            // public Predicate<ImageInfo> keeperPredicate = null;
            I4 + "keeperPredicate:                     " +
                OBJ_TO_CLASS_NAME(this.keeperPredicate) + 

            '\n' +


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Avoiding Hangs and Locks with a TimeOut
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "Avoiding Hangs and Locks with a TimeOut:\n" +

            // public long maxDownloadWaitTime = 0;
            I4 + "maxDownloadWaitTime:                 " + this.maxDownloadWaitTime + '\n' +

            // public TimeUnit waitTimeUnits = null;
            I4 + "waitTimeUnits:                       " + this.waitTimeUnits + '\n' +

            '\n' +


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // USER AGENT
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            "Using a User-Agent:\n" +

            // public String userAgent = DEFAULT_USER_AGENT;
            I4 + "userAgent:                           " + this.userAgent + '\n' +

            // public boolean alwaysUseUserAgent = false;
            I4 + "alwaysUseUserAgent:                  " + this.alwaysUseUserAgent + '\n' +

            // public boolean retryWithUserAgent = true;
            I4 + "retryWithUserAgent:                  " + this.retryWithUserAgent + '\n';
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Clone & Clone-Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Builds a clone of {@code 'this'} instance
     * 
     * @return The copied instance.  Note that this is a <B STYLE='color: red;'>shallow</B> clone,
     * rather than a <B STYLE='color: red;'>deep</B> clone.  The references within the returned
     * instances are <I>the exact same references as are in {@code 'this'} instance</I>.
     */
    public Request clone()
    { return new Request(this); }

    // Used by 'clone()'.  This constructor only configures the 'final' fields
    private Request(Request r)
    {
        // public final URL originalPageURL;
        this.originalPageURL = r.originalPageURL;

        // private final Iterable<String> source;
        this.source = r.source;

        // private final int size;
        this.size = r.size;

        // final IntFunction<String> counterPrinter;
        this.counterPrinter = r.counterPrinter;

        // private final Vector<String[]> b64Images;
        this.b64Images = r.b64Images;        

        // private int b64Pos = 0;
        this.b64Pos = r.b64Pos;

        // private final Vector<Exception> tagNodeSRCExceptions;
        this.tagNodeSRCExceptions = r.tagNodeSRCExceptions;

        // private int tnExPos = 0;
        this.tnExPos = r.tnExPos;

        // public Verbosity = Verbosity.Normal;
        this.verbosity = r.verbosity;        


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Location-Decisions for Saving an Image File
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // public Function<ImageInfo, File> targetDirectoryRetriever = null;
        this.targetDirectoryRetriever = r.targetDirectoryRetriever;

        // public Consumer<ImageInfo> imageReceiver = null;
        this.imageReceiver = r.imageReceiver;

        // public String targetDirectory = null;
        this.targetDirectory = r.targetDirectory;
    

        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // File-Name given to an Image File
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // public String fileNamePrefix = null;
        this.fileNamePrefix = r.fileNamePrefix;

        // public boolean useDefaultCounterForImageFileNames = true;
        this.useDefaultCounterForImageFileNames = r.useDefaultCounterForImageFileNames;

        // public Function<ImageInfo, String> getImageFileSaveName = null;
        this.getImageFileSaveName = r.getImageFileSaveName;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // BOOLEAN'S: Which Image Files to Save, and Which to Skip
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // public boolean skipOnDownloadException = false;
        this.skipOnDownloadException = r.skipOnDownloadException;

        // public boolean skipOnB64DecodeException = false;
        this.skipOnB64DecodeException = r.skipOnB64DecodeException;

        // public boolean skipOnTimeOutException = false;
        this.skipOnTimeOutException = r.skipOnTimeOutException;

        // public boolean skipOnNullImageException = false;
        this.skipOnNullImageException = r.skipOnNullImageException;

        // public boolean skipOnImageWritingFail = false;
        this.skipOnImageWritingFail = r.skipOnImageWritingFail;

        // public boolean skipOnUserLambdaException = false;
        this.skipOnUserLambdaException = r.skipOnUserLambdaException;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // USER-PREDICATE'S & BOOLEAN'S: Which Image Files to Save, and Which to Skip
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // public Predicate<URL> skipURL = null;
        this.skipURL = r.skipURL;

        // public boolean skipBase64EncodedImages = false;
        this.skipBase64EncodedImages = r.skipBase64EncodedImages;

        // public Predicate<ImageInfo> keeperPredicate = null;
        this.keeperPredicate = r.keeperPredicate;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Avoiding Hangs and Locks with a TimeOut
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // public long maxDownloadWaitTime = 0;
        this.maxDownloadWaitTime = r.maxDownloadWaitTime;

        // public TimeUnit waitTimeUnits = null;
        this.waitTimeUnits = r.waitTimeUnits;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // USER AGENT
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // public String userAgent = DEFAULT_USER_AGENT;
        this.userAgent = r.userAgent;

        // public boolean alwaysUseUserAgent = false;
        this.alwaysUseUserAgent = r.alwaysUseUserAgent;

        // public boolean retryWithUserAgent = true;
        this.retryWithUserAgent = r.retryWithUserAgent;
    }
}