Upgrade.java.html

package Torello.JavaDoc;

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

import Torello.Java.Additional.RetN;

import Torello.JDUInternal.MainJDU.ClassUpgradeData.*;

import Torello.JDUInternal.Features.STATS.StatsInternal;

import static Torello.Java.C.*;

import Torello.JDUInternal.Messager.Messager;
import Torello.JDUInternal.Messager.MsgControl;
import Torello.JDUInternal.Messager.MsgVerbose;

import Torello.JDUInternal.SimpleFeatures.LinksChecker;

import Torello.HTML.Tools.SyntaxHiLite.HiLiteCache;
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 StatsInternal stats = new StatsInternal();


    // ********************************************************************************************
    // ********************************************************************************************
    // 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.
     */
    @LinkJavaSource(handle="MainConstructor")
    public Upgrade(final String rootJavaDocDirectory, final String... rootSourceFileDirectories)
    { 
        final RetN r = MainConstructor.run(rootJavaDocDirectory, rootSourceFileDirectories);
        this.pathsTypesBuilder.rootJavaDocDirectory         = r.GET(1);
        this.pathsTypesBuilder.rootSourceFileDirectories    = r.GET(2);
    }

    /**
     * <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()
    {
        return Torello.JDUInternal.MainJDU.API_RUN.runTheUpgrader(
            this.predicatesBuilder.build(),
            this.settingsBuilder.build(),
            this.pathsTypesBuilder, // This class cannot be built, yet, one last thing to compute!
            this.stats
        );
    }

    /**
     * <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();
                HiLiteCache.initializeOrClear(argv[1], null);
            }

            HiLiteCache CACHE = new HiLiteCache(argv[1]);
            upgrader.useHiLiterCache(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>
     */
    @LinkJavaSource(handle="SetEntityFilters", name="setRemoveAllDetailsFilter")
    public Upgrade setRemoveAllDetailsFilter
        (Entity entity, Predicate<? super String> cietCanonicalNameFilter)
    {
        SetEntityFilters.setRemoveAllDetailsFilter
            (entity, cietCanonicalNameFilter, this.predicatesBuilder);
        return this;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_HL_ALL_DET_F>
     * @param cietCanonicalNameFilter <EMBED CLASS='external-html' DATA-FILE-ID=U_CCNF>
     */
    @LinkJavaSource(handle="SetEntityFilters", name="setHiLiteAllDetailsFilter")
    public Upgrade setHiLiteAllDetailsFilter
        (final Entity entity, final Predicate<? super String> cietCanonicalNameFilter)
    {
        SetEntityFilters.setHiLiteAllDetailsFilter
            (entity, cietCanonicalNameFilter, this.predicatesBuilder);
        return this;
    }

    /**
     * <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;
        MsgControl.setVerbosityLevel(verbosity.level);
        if (verbosity.level == 3) MsgVerbose.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;
        MsgControl.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)
     */
    @LinkJavaSource(handle="LogFile")
    public Upgrade setLogFile(final String logFileName)
    { LogFile.set(logFileName, this.settingsBuilder, this.logFileHeader); 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
     */
    @LinkJavaSource(handle="GlobalEmbedTags", name="setMapFile")
    public Upgrade setProjectGlobalEmbedTagsMapFile(final String tagIDMapFileName)
    {
        this.stats = GlobalEmbedTags.setMapFile(tagIDMapFileName, this.settingsBuilder);
        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
     */
    @LinkJavaSource(handle="GlobalEmbedTags", name="setMap")
    public Upgrade setProjectGlobalEmbedTagsMap(ReadOnlyMap<String, String> tagIDMap)
    {
        this.stats = GlobalEmbedTags.setMap(tagIDMap, this.settingsBuilder);
        return this;
    }


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


    /**
     * Convenience Method.
     * <BR />Invokes: {@link HiLiter#getDefault(HiLiteCache, String, String)}
     * <BR />And-Then: {@link #setHiLiter(HiLiter)}
     */
    public Upgrade useHiLiterCache(HiLiteCache cache)
    {
        setHiLiter(HiLiter.getDefault(cache, "vim", "native"));
        this.settingsBuilder.hlCache = 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 hiLiterCacheDirectoryName 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 useHiLiterCache(String hiLiterCacheDirectoryName)
    {
        // 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(hiLiterCacheDirectoryName);
    
        if (! f.exists())
        {
            f.mkdirs();
            HiLiteCache.initializeOrClear(hiLiterCacheDirectoryName, null);
        }

        HiLiteCache cache = new HiLiteCache(hiLiterCacheDirectoryName);

        useHiLiterCache(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;
    }

    /**
     * Retrieve the currently assigned {@link HiLiter} instance.
     * @return The most recently assigned {@link HiLiter} instance.
     */
    public HiLiter getCurrentHiLiter() { return this.settingsBuilder.hiLiter; }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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;
    }

    /**
     * Retrieve the File-Name of the Favicon, if one has been assigned.
     * @return The currently assigned favicon file-name, or null if a favicon was not assigned
     */
    public String getFaviconImageFileName()
    { return this.settingsBuilder.faviconImageFileName; }


    /**
     * <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)
     */
    @LinkJavaSource(handle="TabsPolicy")
    public Upgrade setTabsPolicy(int spacesPerTab, boolean relativeOrAbsolute)
    { TabsPolicy.set(spacesPerTab, relativeOrAbsolute, this.settingsBuilder); 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;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_PKG_LIST_BP>
     * @param packageList Instances of {@link Torello.Java.Build}'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;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=U_SET_PKG_LIST_STR>
     * @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.
     */
    @LinkJavaSource(handle="OverviewFrameSorter")
    public Upgrade setOverviewFrameSorter(String[] sectionNames, String[][] sectionContents)
    { OverviewFrameSorter.set(sectionNames, sectionContents, this.settingsBuilder); 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; }

}