Upgrade.java.html

package Torello.JavaDoc;

import Torello.Java.*;
import Torello.HTML.*;
import Torello.JDUInternal.DataClasses.ClassUpgradeData.*;
import Torello.JDUInternal.Throwables.*;

import static Torello.Java.C.*;

import Torello.JDUInternal.GeneralPurpose.Messager;
import Torello.JDUInternal.GeneralPurpose.MessagerVerbose;

import Torello.JDUInternal.JDU_MAIN.*;

import Torello.JDUInternal.HTMLProcessors.Other.LinksChecker;

import Torello.JDUInternal.UserConfigReaders.RetrieveEmbedTagMapPropFiles;

import Torello.Java.HiLiteMe.Cache;
import Torello.HTML.Tools.Images.IF;

import Torello.Java.ReadOnly.ReadOnlyMap;
import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlyArrayList;

import Torello.Java.Build.BuildPackage;

import java.util.*;
import java.io.*;
import java.util.stream.*;
import java.util.function.*;


/**
 * The primary builder and configuration class for the Java Doc Upgrade Process, having many
 * customizations that may be requested using the customize-settings methods available here.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=UPGRADE>
 */
public class Upgrade
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Public-Static Constant/Final Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** The name of the favicon-file (without extension).  This filename may not be changed. */
    public static final String FAVICON_FILE_NAME = "favicon";

    /** The name of the (very brief) {@code '.js'} file. */
    public static final String JAVA_SCRIPT_FILE_NAME = "JDU.js";


    // ********************************************************************************************
    // ********************************************************************************************
    // Private Fields (all are final/Constants - except "Stats")
    // ********************************************************************************************
    // ********************************************************************************************


    // These are acctually for Internal-Use, and shouldn't be public.  Unfortunately due to Java's
    // leaving out the 'friend' key-word from C/C++, these have to be public in order to share them
    // with the Internal-Only Packages in JavaDoc-Upgrader.

    private final UpgradePredicates.Builder  predicatesBuilder  = new UpgradePredicates.Builder();
    private final UpgradeSettings.Builder    settingsBuilder    = new UpgradeSettings.Builder();
    private final PathsAndTypes.Builder      pathsTypesBuilder  = new PathsAndTypes.Builder();

    // Used by the log-file header string below
    private final String dateTimeStr =
        StringParse.dateStr('-') + " " + StringParse.timeStr(':');

    // Prepended to the log-file that may (or may not) be saved to disk, or an Appendable
    private final String logFileHeader = 
        "<HTML>\n<HEAD>\n" +
        "<TITLE>Log " + dateTimeStr + "</TITLE>\n" +
        "<STYLE type='text/css'>\n" + C.getCSSDefinitions() + "\n</STYLE>\n" +
        "</HEAD>\n" +
        "<BODY STYLE='margin: 1em; background: black; color: white;'>\n\n" +
        "<H1>JavaDoc Upgrader Log</H1>\n" +
        "<CODE>" + dateTimeStr + "</CODE>\n" +
        "<PRE>\n\n";

    // used internally
    private static final TextNode NEWLINE = new TextNode("\n");

    // NOTE: This isn't final....  It can be re-constructed in this class....
    private Stats stats = new Stats();


    // ********************************************************************************************
    // ********************************************************************************************
    // Building / Constructor, Running the Upgrader
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This returns a new instance of this class.  It will have all empty and null settings, except
     * the root-directory descriptors.  It must be initialized with the various builder methods.
     * 
     * <BR /><BR />
     * This constructor must tell the Upgrader (Builder) which directory contains {@code '.java'}
     * Source-Files, and which directory shall contain Java-Doc Generated HTML Documentation Pages.
     * 
     * @param rootJavaDocDirectory This is the output directory that was used for the last call to
     * the JavaDoc Utility.  The Upgrade Logic should expect to find all class, interface and
     * enumerated types to be hilited in this directory.  This parameter may not be null.
     * 
     * @param rootSourceFileDirectories This is the location where the {@code '.java'} source files
     * for the classes, interfaces and enumerated types named by your list files are stored.  This
     * parameter may not be null; at least one directory must be passed.  If you have multiple
     * source-code directories, then pass all of them, and whenever a JavaDoc {@code '.html'} file
     * is loaded from disk, all source-code directories will be searched until the source-code is
     * found.
     * 
     * @throws UpgradeException This exception will throw if either of these directories cannot be
     * found, or may not be accessed.  The {@code 'getCause()'} method of the exception will
     * provide more details of the specific error that occurred.
     */
    public Upgrade(String rootJavaDocDirectory, String... rootSourceFileDirectories)
    {
        // System.out.println("rootJavaDocDirectory = [" + rootJavaDocDirectory + "]\n" +
        //                    "rootSourceFileDirectory = [" + rootSourceFileDirectory + "]");

        Objects.requireNonNull(
            rootJavaDocDirectory,
            "You have passed 'null' to parameter 'rootJavaDocDirectory'"
        );

        Objects.requireNonNull(
            rootSourceFileDirectories,
            "You have passed 'null' to parameter 'rootSourceFileDirectories'"
        );

        // NOTE: Java seems to have no problem with '.' and '..' inside of a File-Name
        if (StrCmpr.containsOR(rootJavaDocDirectory, "*", "?"))

            throw new UpgradeException(
                "The Root JavaDoc Directory String you have passed contains either the '*' " +
                "character, or the '?', but these is not allowed."
            );

        // Check for these errors inside the Root Source Directories too.
        for (String s : rootSourceFileDirectories) if (StrCmpr.containsOR(s, "*", "?"))

            throw new UpgradeException(
                "One of the Root Source Directory Strings that you have passed contains either " +
                "the '*' character, or the '?', but these is not allowed."
            );

        if (rootSourceFileDirectories.length == 0) throw new UpgradeException(
            "You have not passed any source-code directories to parameter " +
            "'rootSourceFileDirectories'"
        );

        /*
        // THIS HAS TO BE MOVED / COPIED
        if (rootJavaDocDirectory.length() > 0)
            UpgradeException.checkFileExistsAndCanAccess
                (rootJavaDocDirectory, "Root '.html' Java-Doc Documentation Page Directory");
        */

        for (String rootSourceDir : rootSourceFileDirectories)
            if (rootSourceDir.length() > 0)
                UpgradeException.checkFileExistsAndCanAccess
                    (rootSourceDir, "Root '.java' Source File Directory");

        // Easier to type "rsd" in the code below
        String[] rsd = new String[rootSourceFileDirectories.length];


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Ensure File.separator is at the end of each of these directory-names - except dir ""
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // If the directory is the "Current Working Directory" - which is specified by the
        // Zero-Length-String (a.k.a ""), then a trailing File.separator should **NOT** be added.
        // All other directory names must end with the File.separator
        //
        // NOTE: For checking that a directory exists and can be accessed (the previous lines of
        //       code), the class java.io.File doesn't require that there be a trailing File
        //       Separator.  However, in this package (the JD-Upgrader Package), appending file
        //       names to these root-directories mandates that the File-Separator be present at the
        //       end of each of these directory-names - except, of course, the "" directory - which
        //       is the "Current Working Directory."
        //
        // SPECIFICALLY: Later on when these Upgrade-Fields are actually used by the class
        //               "MainFilesProcessor" - making sure these directory-names end with '/' is
        //               where this stuff actually comes into play

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

            // DON'T FORGET: This *DOES NOT* end with File.separator - but it doesn't have to!
            if (rootSourceFileDirectories[i].length() == 0)
                rsd[i] = "";

            else if (rootSourceFileDirectories[i].endsWith(File.separator))
                rsd[i] = rootSourceFileDirectories[i];

            else
                rsd[i] = rootSourceFileDirectories[i] + File.separator;

        // if (rsd == null) System.out.println("rsd is null!!!");
        // else System.out.println(Arrays.toString(rsd));
        this.pathsTypesBuilder.rootSourceFileDirectories = ReadOnlyList.of(rsd);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Make sure the File.separator is here too, unless Root-JD-Dir is the CWD (the "" dir)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // This *DOES NOT* end with File.separator - but it doesn't have to!
        if (rootJavaDocDirectory.length() == 0)
            this.pathsTypesBuilder.rootJavaDocDirectory = "";

        else if (rootJavaDocDirectory.endsWith(File.separator))
            this.pathsTypesBuilder.rootJavaDocDirectory = rootJavaDocDirectory;

        else
            this.pathsTypesBuilder.rootJavaDocDirectory = rootJavaDocDirectory + File.separator;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_UPGRADE>
     * 
     * @return This returns the statistics computed for the upgrade process.  See class
     * {@link Stats} for more information.  A complete listing of the information contained by
     * the tables in a {@code 'Stats'} instance may be viewed by clicking the {@code 'Stats'}
     * link at the top-right of this page.
     * 
     * <BR /><BR />If the Upgrade-Process had unrecoverable errors, null is returned.
     */
    public Stats upgrade()
    {
        if (this.pathsTypesBuilder.rootJavaDocDirectory.length() > 0)

            UpgradeException.checkFileExistsAndCanAccess(
                this.pathsTypesBuilder.rootJavaDocDirectory,
                "Root '.html' Java-Doc Documentation Page Directory"
            );

        final UpgradePredicates   predicates  = this.predicatesBuilder.build();
        final UpgradeSettings     settings    = this.settingsBuilder.build();

        try
        {
            Preliminaries.run(settings, pathsTypesBuilder);

            final PathsAndTypes pathsTypes = this.pathsTypesBuilder.build();

            if (Messager.hadErrors()) return null;

            LoopJavaPackages.run(predicates, settings, pathsTypes, stats);

            if (Messager.hadErrors()) return null;

            this.stats.saveStatsHTMLFile(pathsTypes.rootJavaDocDirectory);
        }

        catch (ReachedMaxErrors rme)
        { System.out.println("Reached Maximum Number of Errors.  Exiting"); return null; }

        // Currently Ignoring: HiLiteException
        catch (JavaDocError | HiLiteError | ParseException | UpgradeException e)
        {
            System.out.println(e.getClass().getSimpleName() + " thrown.  Exiting.\n");
            return null;
        }

        catch (Throwable t)
        {
            System.out.println(
                '\n' +
                "****************************************************************\n" +
                EXCC.toString(t) +
                "****************************************************************\n" +
                "Unexpected Throw, Exiting."
            );

            return null;
        }

        finally
        {
            if (this.settingsBuilder.hlmCache != null)
                this.settingsBuilder.hlmCache.persistMasterHashToDisk();
        }

        if (settings.linksChecker != null) settings.linksChecker.runCheck();

        return this.stats; // Perhaps this is useful to the end-user, perhaps not.
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_MAIN>
     * @param argv This is the argument received from the command line.
     */
    public static void main(String[] argv) throws Exception
    {
        Upgrade upgrader = new Upgrade(argv[0], "");

        if (argv.length == 1) upgrader.upgrade();

        else if (argv.length == 2)
        {
            java.io.File f = new java.io.File(argv[1]);

            if (! f.exists())
            {
                f.mkdirs();
                Cache.initializeOrClear(argv[1], null);
            }

            Cache CACHE = new Cache(argv[1]);
            upgrader.useHiLiteServerCache(CACHE).upgrade();
            CACHE.persistMasterHashToDisk();
        }

        else System.out.println("Failed, expected one or two arguments");
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Filter-Predicates
    // ********************************************************************************************
    // ********************************************************************************************


    /**  Write an explanation*/
    @SuppressWarnings("unchecked")
    public Upgrade setRemoveAllDetailsFilter(Predicate<? super String> cietCanonicalNameFilter)
    {
        this.predicatesBuilder.removeAllDetailsFilter =
            (Predicate<String>) cietCanonicalNameFilter;

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_REM_ALL_DET_F>
     * @param entity Specifies which HTML Detail-Section to remove.
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    public Upgrade setRemoveAllDetailsFilter
        (Entity entity, Predicate<? super String> cietCanonicalNameFilter)
    {
        @SuppressWarnings("unchecked")
        Predicate<String> p = (Predicate<String>) cietCanonicalNameFilter;

        switch (Objects.requireNonNull(entity))
        {
            case METHOD:
                this.predicatesBuilder.removeAllMethodDetailsFilter = p;
                return this;

            case CONSTRUCTOR:
                this.predicatesBuilder.removeAllConstructorDetailsFilter = p;
                return this;

            case FIELD:
                this.predicatesBuilder.removeAllFieldDetailsFilter = p;
                return this;

            case ENUM_CONSTANT:
                this.predicatesBuilder.removeAllECDetailsFilter = p;
                return this;

            case ANNOTATION_ELEM:
                this.predicatesBuilder.removeAllAEDetailsFilter = p;
                return this;

            case INNER_CLASS:
                throw new IllegalArgumentException(
                    "You have passed Entity.INNER_CLASS to parameter 'entity', but JavaDoc HTML " +
                    "Web-Pages do not have a Nested-Type / Inner-Class Details-Section to remove " +
                    "in the first place."
                );

            default: throw new UnreachableError();
        }
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_HL_ALL_DET_F>
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    public Upgrade setHiLiteAllDetailsFilter
        (Entity entity, Predicate<? super String> cietCanonicalNameFilter)
    {
        @SuppressWarnings("unchecked")
        Predicate<String> p = (Predicate<String>) cietCanonicalNameFilter;

        switch(Objects.requireNonNull(entity))
        {
            case METHOD:
                this.predicatesBuilder.hiLiteAllMethodsFilter = p;
                return this;

            case CONSTRUCTOR:
                this.predicatesBuilder.hiLiteAllConstructorsFilter = p;
                return this;

            case FIELD:
                this.predicatesBuilder.hiLiteAllFieldsFilter = p;
                return this;

            case ENUM_CONSTANT:
                this.predicatesBuilder.hiLiteAllECsFilter = p;
                return this;

            case ANNOTATION_ELEM:
                this.predicatesBuilder.hiLiteAllAEsFilter = p;
                return this;

            case INNER_CLASS:
                throw new IllegalArgumentException();

            default: throw new UnreachableError();
        }
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_SUMM_REM_F>
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    @SuppressWarnings("unchecked")
    public Upgrade setSummaryRemoveFilter(Predicate<? super String> cietCanonicalNameFilter)
    {
        this.predicatesBuilder.summaryRemoveFilter = (Predicate<String>) cietCanonicalNameFilter;
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_HL_SCF_F>
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    @SuppressWarnings("unchecked")
    public Upgrade setHiLiteSourceCodeFileFilter(Predicate<? super String> cietCanonicalNameFilter)
    {
        this.predicatesBuilder.hiLiteSourceCodeFileFilter =
            (Predicate<String>) cietCanonicalNameFilter;

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_CSS_TAGS_F>
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    @SuppressWarnings("unchecked")
    public Upgrade setCSSTagsFilter(Predicate<? super String> cietCanonicalNameFilter)
    {
        this.predicatesBuilder.cssTagsFilter = (Predicate<String>) cietCanonicalNameFilter;
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_VAL_HTML_F>
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    @SuppressWarnings("unchecked")
    public Upgrade setValidateHTMLFilter(Predicate<? super String> cietCanonicalNameFilter)
    {
        this.predicatesBuilder.validateHTMLFilter = (Predicate<String>) cietCanonicalNameFilter;
        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Setting Features: Output Printing and Log-File
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_VERBOSITY_LVL>
     * @param verbosity One of the four available {@link Verbosity} constants.
     */
    public Upgrade setVerbosityLevel(Verbosity verbosity)
    {
        this.settingsBuilder.verbosityLevel = verbosity.level;
        Messager.setVerbosityLevel(verbosity.level);
        if (verbosity.level == 3) MessagerVerbose.setVerbose();
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_LOG_FILE_APND>
     * @param logFile An {@code Appendable} to be used for backing-up / saving Log-Writes.
     */
    public Upgrade setLogFile(Appendable logFile)
    {
        this.settingsBuilder.logFile = logFile;
        Messager.setLogAppendable(logFile);

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_LOG_FILE_FN>
     * @param logFileName File-Name of a writeable File, to be used for backuping-up Log-Writes
     * @throws UpgradeException If the File provided cannot be written to.
     * @see UpgradeException#checkFileIsWriteable(String, String, String)
     */
    public Upgrade setLogFile(String logFileName)
    {
        // This is just used / passed to the "Exception Checker" (below) to build a more
        // readable Exception-Message.

        String fileDescription = "Disk / File-System Upgrader Log-Dump File";

        // Write log-file header.  Check that the log-file is accessible and writable.
        UpgradeException.checkFileIsWriteable(logFileName, fileDescription, logFileHeader);

        // Build a java.util.function.Consumer<String> 
        // This consumer will function as the log-file write-mechanism.

        this.settingsBuilder.logFile = new Appendable()
        {
            // This method is never actually used by the log-writes in JD-Upgrader.  Realize that
            // writing to the log, and actually check-pointing the log to disk are not the same
            // thing.  This appendable is used for actually writing out the log contents to a
            // flat-file (or any user-provided output/storing mechanism that the user can think of)
            //
            // The user has the option of writing the log-contents to some other, user-specified,
            // appendable that does whatever it wants with the log-contents.
            //
            // But whatever it is! - Check-pointing the log to it's output is only done in the
            // class Messager - using the method: Messager.checkPointLog();
            //
            // FURTHERMORE: The method "Messager.checkPointLog()" is only invoked twice!  Once by
            //              the class "ExtraFilesProcessor" and once by "MainFilesProcessor"

            public Appendable append(char c) // AGAIN: Not used
            { throw new UnreachableError(); }

            public Appendable append(CharSequence s, int start, int end) // NOT USED
            { throw new UnreachableError(); }

            // Invoked only once: In Messager.checkPointLog()
            public Appendable append(CharSequence s) 
            {
                try
                    { FileRW.appendToFile(s, logFileName); }

                catch (IOException ioe)
                {
                    throw new UpgradeException
                        ("Cannot write to log-file: [" + logFileName + "]", ioe);
                }

                return this;
            }
        };

        Messager.setLogAppendable(this.settingsBuilder.logFile);

        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // The HTML <EMBED> tag.  These can be used to provide more processing to the user.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_EMBED_TAG_F>
     * @param tagIDMapFileName A Java {@code '.properties'} File-Name mapping File-ID's to Files.
     * @throws UpgradeException If there are any problems that occur while loading the file
     */
    public Upgrade setProjectGlobalEmbedTagsMapFile(String tagIDMapFileName)
    {
        if (tagIDMapFileName == null) throw new UpgradeException
            ("The parameter 'tagIDMapFileName' (as a String) was passed NULL.");

        File tagIDMapFile = new File(tagIDMapFileName);

        if (! tagIDMapFile.exists()) throw new UpgradeException
            ("The <EMBED> Tag ID Map File Provided doesn't exist:\n[" + tagIDMapFileName + "]");

        if (! tagIDMapFile.isFile()) throw new UpgradeException
            ("The <EMBED> Tag ID Map File Provided isn't a file:\n[" + tagIDMapFileName + "]");

        // MESSAGER:
        //  1) INVOKES:     println, assertFailGeneralPurpose
        //  2) INVOKED-BY:  MainFiesProcessor (main-loop, once), Upgrade (once)
        //  3) RETURNS:     Map<String, String>
        //  4) THROWS:      UpgradeException

        ReadOnlyMap<String, String> tagIDMap = RetrieveEmbedTagMapPropFiles.readPropertiesFile
            (tagIDMapFile);

        if (tagIDMap == null) throw new UpgradeException
            ("tagIDMapFileName: Could not Load.\n[" + tagIDMapFileName + "]");
 
        // NOTE: For "Project Global Tags Map" the "relative-directory" string is the empty
        //       String.  (That is the empty-string parameter in the method call below)
        //
        // MESSAGER:
        //  1) INVOKES:     println, userErrorContinue (only non-throwing Messager methods)
        //  2) INVOKED BY:  Upgrade (twice), MainFilesProcessor (once)
        //  3) RETURNS:     TRUE ==> no errors, FALSE if there were any errors
        //  4) THROWS:      NO EXPLICIT THROWS STATEMENTS

        Messager.setCurrentFileName(tagIDMapFileName, "<EMBED> Tag ID Map Properties File");

        boolean res =
            RetrieveEmbedTagMapPropFiles.checkMap(tagIDMap, this.settingsBuilder.checkBalance, "");

        if (! res) throw new UpgradeException(
            "There were errors when checking the HTML Validity of the External-HTML Global " +
            "<EMBED> Tag Map '.properties' File:\n" +
            "    [" + tagIDMapFileName + "]"
        );

        // Copy the Embed-Tag Map, (ID ==> FileName Map) into 'this' (internally-stored) map.
        // this.settingsBuilder.projectGlobalEmbedTagsMap.clear();
        // this.settingsBuilder.projectGlobalEmbedTagsMap.putAll(tagIDMap);

        this.settingsBuilder.projectGlobalEmbedTagsMap = tagIDMap;


        // Register this with the 'Stats' class.  This keeps a count of the use of each of these
        // tags in Java Doc Pages, and outputs a 'Stats.html' file at the end.

        this.stats = new Stats(this.settingsBuilder.projectGlobalEmbedTagsMap);

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_EMBED_TAG_MAP>
     * @param tagIDMap This should map a {@code 'DATA-FILE-ID'} to an {@code '.html'} File-Name
     */
    public Upgrade setProjectGlobalEmbedTagsMap(ReadOnlyMap<String, String> tagIDMap)
    {
        if (tagIDMap == null) throw new UpgradeException
            ("The parameter 'tagIDMap' (a java.util.Map<String, String>) was passed NULL.");

        // This will check each line on the map, and log errors if there are errors
        // 
        // NOTE: For "Project Global Tags Map" the "relative-directory" string is the empty
        //       String.  (That is the empty-string parameter in the method call below)
        // 
        // MESSAGER:
        //  1) INVOKES:     println, userErrorContinue (only non-throwing Messager methods)
        //  2) INVOKED BY:  Upgrade (twice), RetrieveEmbedTagMapPropFiles (once)
        //  3) RETURNS:     TRUE ==> no errors, FALSE if there were any errors
        //  4) THROWS:      NO EXPLICIT THROWS STATEMENTS

        Messager.setCurrentFileName("User Provided Map Instance", "Instance, Not File");

        // This map is the "Project-Global" Tag-Map
        boolean res =
            RetrieveEmbedTagMapPropFiles.checkMap(tagIDMap, this.settingsBuilder.checkBalance, "");

        if (! res) throw new UpgradeException(
            "There were errors when checking the HTML Validity of the External-HTML Global " +
            "EMBED TAG FILES."
        );

        // Copy the Embed-Tag Map, (ID ==> FileName Map) into 'this' (internally-stored) map.
        // this.settingsBuilder.projectGlobalEmbedTagsMap.clear();
        // this.settingsBuilder.projectGlobalEmbedTagsMap.putAll(tagIDMap);

        this.settingsBuilder.projectGlobalEmbedTagsMap = tagIDMap;

        // Register this with the 'Stats' class.  This keeps a count of the use of each of these
        // tags in Java Doc Pages, and outputs a 'Stats.html' file at the end.

        this.stats = new Stats(this.settingsBuilder.projectGlobalEmbedTagsMap);

        // invocation chaining
        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Using Features: The HiLiter & HiLiter-Cache
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link HiLiter#getDefault(HiLiteMe.Cache, String, String)}
     * <BR />And-Then: {@link #setHiLiter(HiLiter)}
     */
    public Upgrade useHiLiteServerCache(HiLiteMe.Cache cache)
    {
        setHiLiter(HiLiter.getDefault(cache, "vim", "native"));
        this.settingsBuilder.hlmCache = cache;
        return this;
    }

    /**
     * Configures the HiLiter to use the Default HiLiter, and use the provided Cache-Directory as
     * the location for Caching HiLited HTML-Files.
     * 
     * @param hiLiteServerCacheDirectoryName The name of the File-System Directory which has 
     * previously saved HiLited HTML-Files.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> If this is the first time using this Cache
     * Directory, and it doesn't exists yet, this directory will be created, and future
     * {@code Upgrade} instances will save &amp; cache HiLited-Source HTML to this directory.
     */
    public Upgrade useHiLiteServerCache(String hiLiteServerCacheDirectoryName)
    {
        // These four lines allow the Upgrade Tool to cache results for documentation web-pages
        // as they are hilited so that future builds will not have to "re-poll" the server when
        // hiliting source-code files that have not changed.  Use as depicted below.
    
        final File f = new File(hiLiteServerCacheDirectoryName);
    
        if (! f.exists())
        {
            f.mkdirs();
            HiLiteMe.Cache.initializeOrClear(hiLiteServerCacheDirectoryName, null);
        }

        HiLiteMe.Cache cache = new HiLiteMe.Cache(hiLiteServerCacheDirectoryName);

        useHiLiteServerCache(cache);

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_HILITER>
     * @param hiLiter Any valid implementation of the {@link HiLiter} interface
     */
    public Upgrade setHiLiter(HiLiter hiLiter)
    {
        this.settingsBuilder.hiLiter = hiLiter;
        return this;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // The Big Kahuna Burger.  That is a tasty burger.  Brad - did I break your concentration?
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_GET_DEF_CSS_FILES>
     * @return All Java-Doc Upgrader {@code '.css'} Files
     * @see #setCustomCSSFiles(CSSFiles)
     */
    public static CSSFiles retrieveDefaultCSSFilesFromJAR()
    {
        return LFEC.readObjectFromFile_JAR
            (Upgrade.class, "data-files/AllCSSFiles.objdat", true, CSSFiles.class);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_CSS_FILES>
     * @param cssFiles All Java-Doc Upgrader {@code '.css'} Files
     * @see #retrieveDefaultCSSFilesFromJAR()
     */
    public Upgrade setCustomCSSFiles(CSSFiles cssFiles)
    {
        this.settingsBuilder.cssFiles = cssFiles;
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_GET_DEF_JS_FILE>
     * @return The <B STYLE='color:red'><I>entire contents</I></B> of the {@code '.js'} File (read
     * from disk), returned as a {@code String}.
     */
    public static String retrieveDefaultJSFileFromJAR()
    {
        return LFEC.readObjectFromFile_JAR
            (Upgrade.class, "data-files/JDU-JS.sdat", true, String.class);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_FAVICON_IF>
     * @param faviconFileFormat An instance of {@link IF} - the Image-Format of the Favicon-File.
     */
    public Upgrade setFaviconFileFormat(IF faviconFileFormat)
    {
        this.settingsBuilder.faviconImageFileName =
            FAVICON_FILE_NAME + '.' + faviconFileFormat.toString();

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_ADD_HEADER_TAGS>
     * @param headerTags HTML-Tags to be inserted into a page's {@code <HEAD>...</HEAD>} Section
     */
    public Upgrade addHeaderTags(Iterable<TagNode> headerTags)
    {
        Vector<HTMLNode> ht = this.settingsBuilder.headerTags;
        for (TagNode tn : headerTags) { ht.add(tn); ht.add(NEWLINE); }
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_ADD_HEADER_BLOCK>
     * @param headerStuff HTML-Block to be inserted into a page's {@code <HEAD>...</HEAD>} Section
     */
    public Upgrade addHeaderBlock(Vector<HTMLNode> headerStuff)
    { this.settingsBuilder.headerTags.addAll(headerStuff);  return this; }

    /** <EMBED CLASS='external-html' DATA-FILE-ID=U_RUN_LINKS_CHECKER> */
    public Upgrade runLinksChecker()
    {
        this.settingsBuilder.linksChecker = new LinksChecker();
        return this;
    }

    /**
     * Sets a tab-replacement policy for code-hilited HTML.
     * 
     * @param spacesPerTab The number of spaces that should be used as a substitue for a
     * tab-character ({@code '\t'}) when hiliting source-code.
     * 
     * @param relativeOrAbsolute When this parameter receives {@code TRUE}, a tab-character is
     * used to symbolize however many spaces are needed to place the cursor at the next 
     * <B STYLE='color: red;'>rounded-integral</B> number-of-spaces - modulo the value in
     * {@code 'spacesPerTab'}.
     * 
     * <BR /><BR />If a tab-charcter is found at index {@code 13} in a line-of-code, and the value
     * passed to {@code 'spacesPerTab'} were {@code 4}, then the number of spaces inserted would be
     * {@code 3}.  This is because precisely {@code 3} spaces would skip to index {@code 16}, which
     * happens to be the next-highest <B STYLE='color: red;'>rounded-multiple</B> of {@code 4}. 
     * 
     * <BR /><BR />When this parameter receives {@code FALSE}, a tab-character is always 
     * replaced by the exact number of space-characters specified by {@code spacesPerTab}.
     * 
     * @throws IllegalArgumentException If a number less than {@code 1} or greater than {@code 20}
     * is passed to parameter {@code 'spacesPerTab'} 
     * 
     * @see StrIndent#setCodeIndent_WithTabsPolicyRelative(String, int, int)
     * @see StrIndent#setCodeIndent_WithTabsPolicyAbsolute(String, int, String)
     */
    public Upgrade setTabsPolicy(int spacesPerTab, boolean relativeOrAbsolute)
    {
        if ((spacesPerTab < 1) || (spacesPerTab > 20)) throw new IllegalArgumentException(
            "A tab-character ('\t') cannot represent less than one or more than twenty " +
            "spaces.  You have passed [" + spacesPerTab + "]"
        );

        final String SPACES = StringParse.nChars(' ', spacesPerTab);

        this.settingsBuilder.indentor = (relativeOrAbsolute)
            ? (String s) -> StrIndent.setCodeIndent_WithTabsPolicyRelative(s, 1, spacesPerTab)
            : (String s) -> StrIndent.setCodeIndent_WithTabsPolicyAbsolute(s, 1, SPACES);

        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_CHECK_BALANCE>
     * @param checkBalance The value of this parameter can turn the balance checker on or off.
     */
    public Upgrade setCheckBalance(boolean checkBalance)
    {
        this.settingsBuilder.checkBalance = checkBalance;
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_EXTRA_TASKS>
     * 
     * @param extraTasks This function-pointer may be used to, sort-of, do extra processing on a
     * JavaDoc HTML Documentation File while the vectorized-html file is already loaded into
     * memory - and parsed.
     * 
     * <BR /><BR />The class {@link JavaDocHTMLFile} provides many accessor methods to retrieve
     * the Summary Tables, and the HTML Details - <I>along with reflection-classes about the
     * {@link Method}'s, {@link Field}'s, etc... that they describe</I>
     */
    public Upgrade setExtraTasks(Consumer<JavaDocHTMLFile> extraTasks)
    {
        this.settingsBuilder.extraTasks = extraTasks;
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_PKGSUMM_CLEAN>
     * @param packageSummaryCleaner Java Lambda for modifying Vectorized-HTML.
     */
    public Upgrade setPackageSummaryCleaner(Consumer<Vector<HTMLNode>> packageSummaryCleaner)
    {
        this.settingsBuilder.packageSummaryCleaner = packageSummaryCleaner;
        return this;
    }

    /** <EMBED CLASS='external-html' DATA-FILE-ID=U_USE_DEFAULT_PSC> */
    public Upgrade useDefaultPackageSummaryCleaner()
    {
        this.settingsBuilder.packageSummaryCleaner = PackageSummaryHTML::defaultCleaner;
        return this;
    }

    /**
     * Often, for the purposes of "development speed" during the development phase of a project,
     * it can be of tremendous benefit to skip, altogether, the Upgrade Process of some of the
     * Packages in a Project.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Filter Behavior:</B>
     * 
     * <BR />Packages which are explicity named by the input parameter list {@code 'packageList'}
     * are <B STYLE='color: red;'><I>INCLUDED</I></B> not
     * <B STYLE='color: red;'><I>EXCLUDED</I></B> by the Internal Upgrder Logic.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Default Setting:</B>
     * 
     * <BR />By default, initiating an {@code upgrade} will cause this Package's internal 
     * Upgrade Logic to iterate <B STYLE='color: red;'><I>ALL</I></B> Packages found / present in
     * the {@code 'javadoc/'} output directory.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Input-Parameter Type:</B>
     * 
     * <BR />If Java-HTML Package "{@link Torello.Java.Build Build}" is not actually being utilized
     * by your Project's Build-System, there is a nearly identical variant of this method that
     * accept's Package-Names as Java {@code String's}, instead of instances of class
     * "{@link BuildPackage}".
     * 
     * <BR /><BR />(Class {@link BuildPackage} is one of the Primary Data-Classes for the Build
     * Tool {@link Torello.Java.Build}).
     * 
     * @param packageList A list of instances of the {@link Torello.Java.Build Build} Package's
     * class {@link BuildPackage}.
     * 
     * @return {@code 'this'} instance, for method-invocation chaining.
     * @see #setPackageList(String[])
     */
    public Upgrade setPackageList(Iterable<BuildPackage> packageList)
    {
        TreeSet<String> ts = new TreeSet<>();
        for (BuildPackage bp : packageList) ts.add(bp.fullName);
        this.predicatesBuilder.packagesToUpgradeFilter = StrFilter.strListKEEP(ts, false)::test;
        return this;
    }

    /**
     * Often, for the purposes of "development speed" during the development phase of a project,
     * it can be of tremendous benefit to skip, altogether, the Upgrade Process of some of the
     * Packages in a Project.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Filter Behavior:</B>
     * 
     * <BR />Packages which are explicity named by the input parameter list {@code 'packageList'}
     * are <B STYLE='color: red;'><I>INCLUDED</I></B> not
     * <B STYLE='color: red;'><I>EXCLUDED</I></B> by the Internal Upgrder Logic.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Default Setting:</B>
     * 
     * <BR />By default, initiating an {@code upgrade} will cause this Package's internal 
     * Upgrade Logic to iterate <B STYLE='color: red;'><I>ALL</I></B> Packages found / present in
     * the {@code 'javadoc/'} output directory.
     * 
     * @param packageList A list of Package-Name's as a {@code String}.
     * @return {@code 'this'} instance, for method-invocation chaining.
     * @see #setPackageList(Iterable)
     */
    public Upgrade setPackageList(String... packageList)
    {
        this.predicatesBuilder.packagesToUpgradeFilter =
            StrFilter.strListKEEP(false, packageList)::test;

        return this;
    }

    /**
     * A Configuration-Setting for requesting that the Upgrader Auto-Generate the original Java
     * {@code 'package-frame.html'} &amp; {@code 'overview-frame.html'} Files.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_GEN_FRAMES>
     * 
     * @param generateFrames The {@code boolean}-Setting for this Configuration-Field
     * @return {@code 'this'} instance, for method-invocation chaining.
     * 
     * @throws UpgradeException If {@code 'generateFrames'} is passed {@code FALSE}, but you have
     * earlier configured / applied an {@code 'overview-frame.html'} sorter.
     * 
     * @see PackageSummaryHTML#JD_FRAMES_WARNING_MESSAGE
     */
    public Upgrade setGenerateFrames(boolean generateFrames)
    {
        this.settingsBuilder.generateFrames = generateFrames;

        if ((! generateFrames) && (this.settingsBuilder.overviewFrameSections != null))

            throw new UpgradeException(
                "Generate-Frames cannot be turned off if an Overview-Frame Sorter has already " +
                "been applied"
            );

        return this;
    }    

    /**
     * Generate and sort an {@code 'overview-frame.html'} File.
     * @param sectionNames List of "Categories" or "Sections" for the packages
     * @param sectionContents List of Packages for each Category / Section.
     * @return {@code 'this'} instance, for method-invocation chaining.
     */
    public Upgrade setOverviewFrameSorter(String[] sectionNames, String[][] sectionContents)
    {
        // This can only be sorted if it is first created / turned-on.
        this.settingsBuilder.generateFrames = true;

        this.settingsBuilder.overviewFrameSections = new ReadOnlyArrayList<String>(sectionNames);

        // Generics & Arrays do not always look so nice...  In the code below:
        //
        // String[][] sectionContents is cast to Object[], to "help" the javac Generics-Processor
        // Object o is then cast back to String[], also to "help" the javac Generics-Processor
        //
        // Note that this.settingsBuilder.overviewFramePackages is declared using type:
        // public ReadOnlyList<ReadOnlyList<String>> overviewFramePackages

        this.settingsBuilder.overviewFramePackages = new ReadOnlyArrayList<ReadOnlyList<String>>(
            (Object o) -> new ReadOnlyArrayList<String>((String []) o),
            (Object[]) sectionContents
        );

        return this;
    }

    // This is only used to prevent the "Overview Frame Sorter" from causing a Messager
    // Exception-Throw when the Build has Opted for a "Quick-Build" - and the Overview
    // Frame Sorter hasn't removed the Quick-Build Packages from its sort!
    // 
    // Later this will also be used for the (upcoming - soon) "UNDER_DEVELOPMENT" BuildPackage 
    // flag.
    // 
    // This is an Internal-Method that is largely completely useless for the end user.  Hence it is
    // Package-Visible (available through the "EXPORT_PORTAL")

    void registerEliminatedBuildPackages(ReadOnlyList<BuildPackage> eliminatedBuildPackages)
    { this.settingsBuilder.eliminatedBuildPackages = eliminatedBuildPackages; }
}