Class Upgrade

  • public class Upgrade
extends java.lang.Object
    JavaDoc Upgrade (Builder) - Documentation.

    This is the class that 'Upgrades' the standard Java Doc '.html' pages into the form that you are reading right now.

    IMPORTANT NOTE: Before any of the features of this Upgrader Tool will function, an outside JAR-library distribution must be included in the Java CLASSPATH environment variable. The link below is a link to the Java Parser JAR. There is a book available about this library, and an internet Gitter.com Support Page (chat-room) hosted by some of the people involved in writing this JAR library. The complete Java Parser Library has many Java '.jar' files associated, but only the core-library is needed for running the tasks in this Upgrade Tool.

    This '.jar' file may be donloaded here:

    http://developer.torello.directory/ralphsReference/jars/javaparser-core-3.16.2.jar

    What follows is an example where some of the initializer fields for this upgrader are actually used. Note that this class has a command-line main(String[]) method available. Recognize that the CLI version of this class does not initialize any of the fields (except possibly the HiLiter Cache), and that this upgrader tool can be run without anything complicated if need be.

    Example:
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
        // The location where JDK's "javadoc" has sent its output
    public static final String LOCAL_JAVADOC_DIR = "javadoc/";

    // A simple two-column text-file which maps FILE-ID's to file-names.
    // The files, themselves, should contain HTML for auto-insert into your documentation.
    public static final String HILITE_EMBEDID_MAP_FILE = "Torello/Build/TXT/ids.txt";

    // Text-file which lists classes, interfaces, etc... whose fields should NOT be syntax-hilited.
    public static final String LEAVEOUT_FIELDS_LIST_FNAME = "Torello/Build/TXT/SkipAllFields.txt";

    // Text-file which lists classes, interfaces, etc... whose source-code file should NOT be hilited.
    public static final String LEAVEOUT_SRCFILES_LIST_FNAME = "Torello/Build/TXT/SkipSrcFile.txt";

    public static final StrFilter HILITE_ALL_FIELDS_PRED = 
        StrFilter.strListREJECT_NOIOE(LEAVEOUT_FIELDS_LIST_FNAME, false);

    public static final StrFilter HILITE_SRC_FILE_PRED =
        StrFilter.strListREJECT_NOIOE(LEAVEOUT_SRCFILES_LIST_FNAME, false);


    The above constants are passed as parameters to the Upgrade Tool's initialization "hamburger stack". The last method invoked on this stack is the run() method.

    Example:
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        // Saves text internally, prints to the log-file, and prints to terminal.
    StorageWriter sw = new StorageWriter();

    // 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.

    String  HILITEME_CACHE  = "cache/";  // directory name
    File    f               = new File(HILITEME_CACHE);

    if (! f.exists())
        { f.mkdirs(); HiLiteMe.Cache.initializeOrClear(HILITEME_CACHE, sw); }
    HiLiteMe.Cache CACHE = new HiLiteMe.Cache(HILITEME_CACHE);

    new Upgrade                             (LOCAL_JAVADOC_DIR, "")
        .setLogFile                         ("log.html")
        .setFaviconFileFormat               (Torello.HTML.Tools.Images.IF.JPG)
        .setEmbedTagsMapFile                (HILITE_EMBEDID_MAP_FILE)
        .setHiLiteAllFieldsFilter           (HILITE_ALL_FIELDS_PRED)
        .setHiLiteSourceCodeFileFilter      (HILITE_SRC_FILE_PRED)
        .useHiLiteServerCache               (CACHE)
        .useDefaultPackageSummaryCleaner    ()
        .upgrade(sw);




    • Field Detail

      • JAVA_DOC_CSS_FILE_NAME

        public static final java.lang.String JAVA_DOC_CSS_FILE_NAME
        The name of the JavaDoc CSS Definitions file. This filename may not be changed.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final String JAVA_DOC_CSS_FILE_NAME = "JavaDoc.css";

      • FAVICON_FILE_NAME

        public static final java.lang.String FAVICON_FILE_NAME
        The name of the favicon-file (without extension). This filename may not be changed.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final String FAVICON_FILE_NAME = "favicon";

      • rootJavaDocDirectory

        protected final java.lang.String rootJavaDocDirectory
        The Root Java Doc output directory. This is usually just 'javadoc/'
        Code:
        Exact Field Declaration Expression:
        1
        protected final String rootJavaDocDirectory;

      • rootSourceFileDirectory

        protected final java.lang.String rootSourceFileDirectory
        The Root Source-Code directory
        Code:
        Exact Field Declaration Expression:
        1
        protected final String rootSourceFileDirectory;

      • faviconImageFileName

        protected java.lang.String faviconImageFileName
        This helps add a favicon to JavaDoc Pages. When this String is set to a non-null value, an HTML Favicon Link will be inserted into each web-page of the code documentation. A favicon is a small graphical image that appears in the top corner of the web-page tabs when viewing a web-page.

        In order to set this field, an image-type file-extension needs to be provided. When the image file-extension is provided, an HTML '<link rel='icon' type='image/jpg' href='../favicon.jpg' />' element will be inserted into each page of the Java-Doc Upgraded Pages.

        ALSO: To maintain simplicity of the tool, the favicon file-name "favicon" cannot be changed. However, the extenion may be set to any of the file extensions provided in class IF - including '.jpg', '.png', etc...

        When the image-type file-extension is set, an HTML '<link rel='icon' type='image/jpg' href='../favicon.jpg' />' element will be inserted into each page of the Java-Doc Upgraded Pages. The specific ../..' String is auto-computed for each page.

        FINALLY: When a favicon link is requested, the actual image file must manually be copied into the java-doc root directory - or the browser will not find the favicon! After running the Java-Doc on your '.html' files, simply copy the 'favicon.EXT' image file to the root output Java Doc directory, and the browser will be able to find the image, using the '<LINK>' element's which this tool will have inserted.
        See Also:
        setFaviconFileFormat(IF), IF
        Code:
        Exact Field Declaration Expression:
        1
        protected String faviconImageFileName = null;

      • VERBOSE_PRINT_STEPS

        protected boolean VERBOSE_PRINT_STEPS
        The steps that the Java-Doc Upgrader Tools is taking are printed to the provided StorageWriter when this field is set to 'TRUE'.

        NOTE: If no instance of StorageWriter is passed to the Upgrader's primary 'run(...)' method, then process-step output will not be displayed - regardless of the value of this 'boolean' field.
        Code:
        Exact Field Declaration Expression:
        1
        protected boolean VERBOSE_PRINT_STEPS = true;

      • logFile

        protected java.util.function.Consumer<java.lang.String> logFile
        Output log information is only sent to the passed instance of StorageWriter, but if a logFile (or any String-Consumer) is provided, this information can be check-pointed to the file-system to prevent large Java StringBuilder instances with hundreds or thousands of log-file String's from slowing down the memory-model or garbage collector.
        See Also:
        setLogFile(java.util.function.Consumer<java.lang.String>), setLogFile(java.lang.String)
        Code:
        Exact Field Declaration Expression:
        1
        protected Consumer<String> logFile = null;

      • embedTagIDTable

        protected final java.util.Hashtable<java.lang.String,​java.lang.String> embedTagIDTable
        This stores the a map of TagID fields to their respective HTML-File File-Names on the file-system. It is used in combination with JavaDoc Source-Code HTML Tags that request "External-HTML" be inserted into a JavaDoc HTML Web-Page.

        This Upgrader feature allows programmers to write more detailed code documentation (comments) for their Java Classes while reducing the 'clutter' in the code. If a particular method or field needs a lot of commenting, simply type up an external '.html' file (leave off the HTML <HEADER>, <BODY> tags) Then, in your 'java' Source-Code File, insert an HTML <EMBED> tag - and the Upgrader will automatically insert all of the HTML in the external-documentation file you have created.

        The 'EMBED' tag needs to look like:

        <EMBED CLASS="external-html" DATA-FILE-ID="SOME_ID">

        You have the ability to insert these tags into the comments of your source-files, because this Upgrader will replace those HTML elements with the HTML found in the file named by this map. See the image below as an example: Notice that all that has to be provided to the tag is a 'DATA-FIILE-ID' attribute. This 'ID' is mapped to a file-system text-file using this map.

        HTML EMBED Tag Example

        The 'embedTagIDTable' is a really simple 'Map' that translates an '<EMBED>' element's DATA-FILE-ID to an '.html' file-name (that you have written) on the file-system. The Embed Tags Map File used by this Library's Build Script may be viewed below, as an example. This is an exhaustive list of all Externally-Linked HTML Pages for the Java HTML library.

        Embed Tags Map File
        See Also:
        setEmbedTagsMapFile(String), setEmbedTagsMap(Map)
        Code:
        Exact Field Declaration Expression:
        1
        protected final Hashtable<String, String> embedTagIDTable = new Hashtable<>();

      • jdCSS

        protected java.lang.String jdCSS
        This should be the contents of the intended CSS Rules written to the file 'JavaDoc.css' which shall live in the root-directory of the javadoc file-tree. A link to this CSS file is inserted into each and every java-doc page that is updated.

        NOTE: This CSS File is only useable if the user has not invoked doNotAddCSSTags(). If the Upgrader is prohibited from adding CSS Tags to Java-Doc generated web-pages, then the CSS Rules will be not be useable by the browser.

        NOTE: The default CSS Rules for the CSS CLASS and ID tags created will be the same ones that are used in this documentation page that you are looking at right now. The default CSS may be changed by assigning a specialized CSS page using the 'setCustomJDCSSFile(String)' method in this class.

        The default CSS File may be viewed here:

        Default CSS File
        See Also:
        setCustomJDCSSFile(String), doNotAddCSSTags()
        Code:
        Exact Field Declaration Expression:
        1
        protected String jdCSS = null;

      • extraTasks

        protected java.util.function.Consumer<CommonParamRecord> extraTasks
        This instance of Consumer<CommonParamRecod> should be registered by the user. This allows a user to modify the HTML of a JavaDoc HTML Web-Page in whatever proprietary or custom manner that you would like. A programmer might wish to add HTML <META> tags to the header, or perhaps add some recurring-automated comments to each method description.

        This java.util.function.Consumer<CommonParamRecord> will receive the same record-instance that is passed to all of the main-operation classes in this library. The most important part to remember is that any modifications to the JavaDoc Web-Page need to be performed on the 'fileVec' parameter.

        NOTE: Modifying HTML is niether difficult, nor tedious, but it does require knowledge of the classes, interfaces, etc. in both the Torello.HTML and the NodeSearch packages. In any case, just about everything you would need to know about a Java Doc HTML page is provided in the parameters of the CommonParamRecord class.
        See Also:
        setExtraTasks(Consumer)
        Code:
        Exact Field Declaration Expression:
        1
        protected Consumer<CommonParamRecord> extraTasks = null;

      • rearrangeFrames

        protected RearrangePkgFrame.PackageItems rearrangeFrames
        This field may be set if you would like to create upgraded Package Frames. It is not important to know how the RearrangePkgFrame class works, but click the link to this internally-used class to read about it.

        The purpose of this is to allow the user to easily change the layout of the 'package-frame.html' page in Java Doc. Later versions of the Java Doc Tool give warning messages that 'Frames' are going to be deprecated. I personally don't really understand why because they add tremendously to the look-and-feel of the page.

        IMPORTANT: Setting this field will also result in the package-summary.html files being re-arranged according to the specified input arrays. Remember that providing a more logical arrangement of the class, interfaces, exceptions, etc... for your JAR Library files can make reading them and browsing them orders of magnitude more lucid and well-thought out.

        Below is a link to example input arrays, and how they should look. The arrays in the link are actually the exact onese used to rearrange the package-frame.html files employed by this Java HTML library.

        Torello.Build.Helper.PackageItems.java

        The changes that can be made are explained more clearly with a simple picture:

        RearrangePkgFrame Example

        The changes made to the package-summary.html HTML Files can be seen here:

        PackageSummaries Example
        See Also:
        setPackageFrames(String[], String[][], String[][][], boolean)
        Code:
        Exact Field Declaration Expression:
        1
        protected RearrangePkgFrame.PackageItems rearrangeFrames = null;

      • summaryItems

        protected RearrangeSummaries.SummaryItems summaryItems
        This is the field that is used to re-arrange "Summary Sections" inside a Java-Doc HTML Page. The "Summary Sections" are a "Table of Contents" for methods, fields, constructors etc... at the top of a Java-Doc Generated Documentation Page. The default version of the "Field Summaries" section, for example, will list the fields inside of a class, but the list itself cannot be partitioned in categories or sub-lists - which can make for more difficult reading. The class RearrangeSummaries allows you to create 'sections' inside this 'Table of Contents' with category-names, and a sorter algorithm of your choosing. This can effectively make much nicer-looking summaries in your documentation pages.

        Below is a sample of what the arrays should look like in order for this upgrader to perform such an upgrade. This is the "Rearrange Summaries" list of arrays used to build the Java HTML Library. This file is quite long, but reading might make it easier to understand what actually belongs inside these arrays. At the very end of the class in this link, the arrays are collated so that they may be passed to: setSummaryRearrange(...)

        Torello.Build.Helper.SummRearrange.java

        For a more visual explanation of what the 'Summary Items' are, please review the following before and after screen clips:

        See Also:
        setSummaryRearrange(String[], String[][], FCM[], ToIntFunction[])
        Code:
        Exact Field Declaration Expression:
        1
        protected RearrangeSummaries.SummaryItems summaryItems = null;

      • checkBalance

        protected boolean checkBalance
        This flag boolean is, by default, set to TRUE. This Upgrade tool uses the class Torello.HTML.Balance to check for validity inside of all HTML files it encounters - including both the externally linked Embed-Tag HTML files, and the JavaDoc generated HTML files. The type of 'validity' that is checked is for unclosed HTML-tags.

        There is more explanation of what consitutes a "Balanced HTML File" in class Balance. To summarize the information there, all that the code really does is to check (for all non-singleton tags, only), that there are an equal number of opening and closing versions of each HTML element. For example, the balance-checker counts the number of '<DIV>' elements and the number of '</DIV>' elements, and if there are not an equal number of them, an exception is thrown. (No more, no less)

        NOTE: Singleton tags (such as <IMG ...>) are not checked because they are not expected to be closed, they are stand-alone tags. The code, here, will also pass on checking attribute-validity. An HTML <IMG> that (accidentally) uses an HREF=... instead of a SRC=..., though erroneous, is an error that is not caught by this checker. Future versions of this tool may work on this problem.

        FINALLY: JavaDoc generates valid HTML, but a programmer who inserts HTML into his comments may encounter situations where this check helps debugging the documentation. There are boundary cases involing the tag '<LI>', as some web-designers feel that it is not necessary to close these tags with a '</LI>', however this checker will not allow this. To allow for unclosed, non-singleton tags, this checker must be turned off.
        See Also:
        setCheckBalance(boolean)
        Code:
        Exact Field Declaration Expression:
        1
        protected boolean checkBalance = true;

      • stats

        protected final Stats stats
        Keeps some statistics about the upgrade / build. View / use after upgrader completes.
        Code:
        Exact Field Declaration Expression:
        1
        protected final Stats stats = new Stats();

      • printStats

        protected boolean printStats
        Requests whether to print the statistics to the output.
        Code:
        Exact Field Declaration Expression:
        1
        protected boolean printStats = true;

      • summaryRemoveFilter

        protected java.util.function.Predicate<java.lang.String> summaryRemoveFilter
        This filter is used to decide which class, interface, enum etc... '.java' Source-Code Files need to avoid having their 'Summary Descriptions' removed. The Java Doc Tool inserts summaries into a Method Summaries, Field Summaries, and Constructor Summaries, section at the top of a Java Doc page. They are at the top of the Java Doc '.html' file.

        NOTE: The default initialization value of 'null' for the 'summaryRemoveFilter' field implies you want this Upgrade Tool to remove the summary text for all Java-Doc '.html' Pages.

        Generally, the English-Language (or any written, human language) HTML description in a Java Doc Comment looks reasonably nice in the details portion of Java-Doc Page. However, in the summaries portion, for just about anything but the most trivial of comments, the JavaDoc Logic (which just abbreviates the comments) rarely produces a nice enough looking 'Summary Description' to be useable. The 'AI' just isn't advanced enough to automatically figure out what you want the summary to say. Therefore, the signature, by itself, ought be enough.

        This default behavior may be changed by selecting and identifying classes, intefaces, etc., which you would like to see retain their abbreviated description summaries.

        Cleaned Summaries look as in the picture below:

        Cleaned Summaries
        See Also:
        setSummaryRemoveFilter(Predicate), doNotRemoveSummaries()
        Code:
        Exact Field Declaration Expression:
        1
        protected Predicate<String> summaryRemoveFilter = null;

      • hiLiteSourceCodeFileFilter

        protected java.util.function.Predicate<java.lang.String> hiLiteSourceCodeFileFilter
        This filter is used to decide which Class, Interface or Enumerated-Type '.java' Source-Code Files will be hilited, and have links to an '.html' file included in their respective Java-Doc '.html' page. The default initialization value of 'null' will result in *all* Java-Doc Pages having a code-hilited HTML Anchor '<A HREF=...>' link inserted into their respective Java-Doc pages. This anchor will link the page to a HiLited-version of the Source-Code '.java' file from which the Java-Doc HTML Page was generated.

        The Do Not HiLite Source-Code Files Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which no 'Source Code' File HiLiting is performed. If you view the Documentation Pages for the classes listed in this file, you will see the automatically-added "Source Code" links are actually manually added by a different portion of the build script.

        The content of this file are loaded into a StrFilter, and passed to setHiLiteSourceCodeFileFilter(Predicate)

        Skip All Source-File HiLiting Text File

        The above file is loaded into this Predicate<String> by calling:
        StrFilter.strListREJECT_NOIOE(String, boolean)

        The HiLited Source Code File procedure is the one which creates links on your Java Doc Pages that look like:

        HiLited Source Code File Link
        See Also:
        setHiLiteSourceCodeFileFilter(Predicate), doNotHiLiteSourceCodeFiles()
        Code:
        Exact Field Declaration Expression:
        1
        protected Predicate<String> hiLiteSourceCodeFileFilter = null;

      • hiLiteAllMethodsFilter

        protected java.util.function.Predicate<java.lang.String> hiLiteAllMethodsFilter
        This filter is used to decide which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have their method bodies hilited and inserted in their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *all* Java-Doc Pages having code-hilited method-bodies inserted into their Java-Doc Pages.

        The Do Not HiLite Methods Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which no 'Method Body' HiLiting is performed. The file is loaded into a StrFilter, and passed to setHiLiteAllMethodsFilter(Predicate)

        Skip All Methods HiLiting Text File

        The above file is loaded into this Predicate<String> by calling:
        StrFilter.strListREJECT_NOIOE(String, boolean)

        The HiLite Method Body procedure is the one which creates segments on your Java Doc Pages that look like:

        HiLited Method Declaration
        See Also:
        setHiLiteAllMethodsFilter(Predicate), doNotHiLiteMethods()
        Code:
        Exact Field Declaration Expression:
        1
        protected Predicate<String> hiLiteAllMethodsFilter = null;

      • hiLiteAllFieldsFilter

        protected java.util.function.Predicate<java.lang.String> hiLiteAllFieldsFilter
        This filter is used to decided which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have their field declarations hilited and inserted in their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *all* Java-Doc Pages having code-hilited field-declarations inserted into their Java-Doc Pages.

        The Do Not HiLite Fields Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which no 'Field Declaration' HiLiting is performed. The file is loaded into a StrFilter, and passed to setHiLiteAllFieldsFilter(Predicate)

        Skip All Fields HiLiting Text File

        The above file is loaded into this Predicate<String> by calling:
        StrFilter.strListREJECT_NOIOE(String, boolean)

        The HiLite Field Declaration procedure is the one which creates segments on your Java Doc Pages that look like:

        HiLited Field Declaration
        See Also:
        setHiLiteAllFieldsFilter(Predicate), doNotHiLiteFields()
        Code:
        Exact Field Declaration Expression:
        1
        protected Predicate<String> hiLiteAllFieldsFilter = null;

      • hiLiteAllConstructorsFilter

        protected java.util.function.Predicate<java.lang.String> hiLiteAllConstructorsFilter
        This filter is used to decided which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have their constructor declarations hilited and inserted in their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *none* of the Java-Doc Pages having code-hilited constructor-declarations inserted into their Java-Doc Pages.

        The HiLite Constructors Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which 'Constructor Declaration' HiLiting is performed. The file is loaded into a StrFilter, and passed to setHiLiteAllFieldsFilter(Predicate)

        HiLite All Constructors Text File

        The above file is loaded into this Predicate<String> by calling:
        StrFilter.strListKEEP_NOIOE(String, boolean)

        The HiLite Constructor Declaration procedure is the one which creates segments on your Java Doc Pages that look like:

        HiLited Contructor Declaration
        See Also:
        setHiLiteAllConstructorsFilter(Predicate), hiLiteConstructors()
        Code:
        Exact Field Declaration Expression:
        1
        protected Predicate<String> hiLiteAllConstructorsFilter = null;

      • cssTagsFilter

        protected java.util.function.Predicate<java.lang.String> cssTagsFilter
        This filter is used to decided which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have CSS-Tags inserted into their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *all* Java-Doc Pages having CSS-Tags inserted into the HTML Elements in their respective JavaDoc Pages.

        The Insert CSS Tags procedure is the one which creates CSS CLASS attributes in your Java Doc Pages that look:

        CSS Tags

        To see the complete list of CSS CLASS attributes that are added to a Java Doc '.html' File, please review class Colorize.

        The default CSS File may be viewed here:

        Default CSS File
        See Also:
        setCSSTagsFilter(Predicate), doNotAddCSSTags()
        Code:
        Exact Field Declaration Expression:
        1
        protected Predicate<String> cssTagsFilter = null;

    • Constructor Detail

      • Upgrade

        public Upgrade​(java.lang.String rootJavaDocDirectory,
               java.lang.String rootSourceFileDirectory)
        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.

        This constructor must tell the Upgrader (Builder) which directory contains '.java' Source-Files, and which directory shall contain Java-Doc Generated HTML Documentation Pages.
        Parameters:
        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.
        rootSourceFileDirectory - This is the location where the '.java' source files for the classes, interfaces and enumerated types named by your list files. This parameter may not be null.
        Throws:
        UpgradeException - This exception will throw if either of these directories cannot be found, or may not be accessed. The 'getCause()' method of the exception will provide more details of the specific error that occurred.
        See Also:
        rootJavaDocDirectory, rootSourceFileDirectory

    • Method Detail

      • turnOffVerboseProcessPrint

        public Upgrade turnOffVerboseProcessPrint()
        This turns off the "verbose" process-step printing information to the log 'StorageWriter' output. This usually helps follow along with Java-Doc Upgrader steps. By default, this field is set to 'TRUE.'
        See Also:
        VERBOSE_PRINT_STEPS
        Code:
        Exact Method Body:
        1
         VERBOSE_PRINT_STEPS = false; return this;

      • setLogFile

        public Upgrade setLogFile​
            (java.util.function.Consumer<java.lang.String> consumerLogFile)
        Log information may be sent anywhere. If you need to save Log information somewhere other than a file on the file-system, pass a Java Lambda that accepts Log File String's
        Parameters:
        consumerLogFile - This may be any lambda which receives log-file writes.
        Returns:
        An instance of 'this' upgrader, for convenience.
        See Also:
        logFile
        Code:
        Exact Method Body:
        1
         this.logFile = consumerLogFile; return this;

      • setLogFile

        public Upgrade setLogFile​(java.lang.String logFileName)
        Log information will be sent to the file-name provided, here. This must be an accessible file on the file-system.
        Parameters:
        logFileName - This may be any file that is accessible on the (UNIX/DOS) filesystem.
        Returns:
        An instance of 'this' upgrader, for convenience.
        Throws:
        UpgradeException - When invoked, this method will attempt to write some preliminary header information to the log-file. If this write fails, an UpgradeException will be thrown.
        See Also:
        UpgradeException.checkFileIsWriteable(String, String, String), logFile
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
         String dateTimeStr = StringParse.dateStr('-') + " " + StringParse.timeStr(':');

 String fileHeader = 
     "<HTML>\n<HEAD>\n" +
     "<TITLE>Log " + dateTimeStr + "</TITLE>\n" +
     "<STYLE type='text/css'>\n" + Shell.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";

 // This is just used / passed to the "Exception Checker" (below) to build a more
 // readable Exception-Message.
 final 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, fileHeader);

 // Build a java.util.function.Consumer<String> 
 // This consumer will function as the log-file write-mechanism.
 logFile = (String s) -> 
 {
     try
         { FileRW.appendToFile(s, logFileName); }
     catch (IOException e)
         { throw new UpgradeException("Cannot write to log-file: [" + logFileName + "]"); }
 };

 return this;

      • setSummaryRemoveFilter

        public Upgrade setSummaryRemoveFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc Web-Pages will have their "Summary Descriptions" removed from the summary tables at the top of a JavaDoc generated web-page. By default this field is null, and when it is - all Java-Doc Pages will have their respective textual, abbreviated "Summary Descriptions" removed from the summary tables which are located at the top of the web-page.

        The filter-parameter ('cietNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate's 'test(String)' method will receive the fully-qualified name of a Java Class, Interface, or Enum (CIET) whose source-code documentation-file is being modified.

        The Predicate should return TRUE if you would like to avoid removing the Field and Method Summary Text from the Field Summaries and Method Summaries for a particular CIET.

        NOTE: If you keep a short '.txt' file that just lists the classes you don't want hilited, you may load that '.txt' file into a Java Predicate using either:



        Cleaned Summaries look as in the picture below:

        Cleaned Summaries
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.
        See Also:
        summaryRemoveFilter, doNotRemoveSummaries(), StrFilter
        Code:
        Exact Method Body:
        1
         this.summaryRemoveFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setHiLiteSourceCodeFileFilter

        public Upgrade setHiLiteSourceCodeFileFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc Web-Pages will get an HTML Anchor Link '<A HREF=...>' that contains a local URL with an '.html' file of the '.java' Source-Code for the Java-Doc Page being updated. By default this field is null, and when it is - all Java-Doc Pages will have their respective source-code files hilited, and will have links such links placed on their their pages.

        The filter-parameter ('cietNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate's 'test(String)' method will receive the fully-qualified name of a Java Class, Interface, or Enum (CIET) whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see the original Java Source-Code ('.java' file) HiLited, and FALSE if the Upgrader should skip the CIET.

        NOTE: If you keep a short '.txt' file that just lists the classes you don't want hilited, you may load that '.txt' file into a Java Predicate using either:



        The HiLited Source Code File procedure is the one which creates links on your Java Doc Pages that look like:

        HiLited Source Code File Link
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.
        See Also:
        doNotHiLiteSourceCodeFiles(), hiLiteSourceCodeFileFilter, StrFilter
        Code:
        Exact Method Body:
        1
         this.hiLiteSourceCodeFileFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setHiLiteAllMethodsFilter

        public Upgrade setHiLiteAllMethodsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc Web-Pages will have all their method-bodies hilited and inserted into the JavaDoc Page. By default this field is 'null', and when it is - all Java-Doc Pages will have their respective method-bodies (Java Source) hilited and inserted into the page.

        The filter-parameter ('cietNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate's 'test(String)' method will receive the fully-qualified name of a Java Class, Interface, or Enum (CIET) whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see the Method Bodies HiLited, and FALSE if the Upgrader should skip hiliting method bodies for the CIET.

        NOTE: If you keep a short '.txt' file that just lists the classes you don't want hilited, you may load that '.txt' file into a Java Predicate using either:



        The HiLite Method Body procedure is the one which creates segments on your Java Doc Pages that look like:

        HiLited Method Declaration
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.
        See Also:
        doNotHiLiteMethods(), hiLiteAllMethodsFilter, StrFilter
        Code:
        Exact Method Body:
        1
         this.hiLiteAllMethodsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setHiLiteAllFieldsFilter

        public Upgrade setHiLiteAllFieldsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc Web-Pages will have all their field-declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default this field is null, and when it is - all Java-Doc Pages will have their respective source-code field-declarations hilited and inserted onto their page.

        The filter-parameter ('cietNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate's 'test(String)' method will receive the fully-qualified name of a Java Class, Interface, or Enum (CIET) whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see the Field Declarations HiLited, and FALSE if the Upgrader should skip hiliting field declarations for the CIET.

        NOTE: If you keep a short '.txt' file that just lists the classes you don't want hilited, you may load that '.txt' file into a Java Predicate using either:



        The HiLite Field Declaration procedure is the one which creates segments on your Java Doc Pages that look like:

        HiLited Field Declaration
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.
        See Also:
        doNotHiLiteFields(), hiLiteAllFieldsFilter, StrFilter
        Code:
        Exact Method Body:
        1
         this.hiLiteAllFieldsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setHiLiteAllConstructorsFilter

        public Upgrade setHiLiteAllConstructorsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc Web-Pages will have all their constructor-declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default this constructor is null, and when it is - all Java-Doc Pages will have their respective source-code constructor-declarations hilited and inserted onto their page.

        The filter-parameter ('cietNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate's 'test(String)' method will receive the fully-qualified name of a Java Class or Enum (CIET) whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see the Constructor Declarations HiLited, and FALSE if the Upgrader should skip hiliting constructor declarations for the CIET.

        NOTE: If you keep a short '.txt' file that just lists the classes you don't want hilited, you may load that '.txt' file into a Java Predicate using either:



        The HiLite Constructor Declaration procedure is the one which creates segments on your Java Doc Pages that look like:

        HiLited Constructor Declaration
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class or Enum.
        See Also:
        hiLiteConstructors(), hiLiteAllConstructorsFilter, StrFilter
        Code:
        Exact Method Body:
        1
         this.hiLiteAllConstructorsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setCSSTagsFilter

        public Upgrade setCSSTagsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc Web-Pages will have internal Java-Doc HTML Elements updated to contain a series of CSS 'CLASS' and CSS 'ID' tags. These tags may then be used with an external CSS-StyleSheet, which makes the task of adding color, font, and border-designs to a Java-Doc Page a lot easier. By default, this field is null - and all pages will have CSS Tags inserted.

        The filter-parameter ('cietNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate's 'test(String)' method will receive the fully-qualified name of a Java Class, Interface, or Enum (CIET) whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see CSS Tags inserted into the HTML, and FALSE if the Upgrader should skip inserting CSS Tagsinto this CIET.

        The Insert CSS Tags procedure is the one which creates CSS CLASS attributes in your Java Doc Pages that look:

        CSS Tags

        NOTE: If you keep a short '.txt' file that just lists the classes you don't want changed, you may load that '.txt' file into a Java Predicate using either:



        The default CSS File used by this upgrader may be viewed here:

        Default CSS File
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.
        See Also:
        doNotAddCSSTags(), cssTagsFilter, StrFilter
        Code:
        Exact Method Body:
        1
         this.cssTagsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • doNotRemoveSummaries

        public Upgrade doNotRemoveSummaries()
        This will set a filter Predicate that returns FALSE for every Class, Interface or Enum. If this method is used, then none of the Java-Doc Upgraded Pages will have their Summaries (at the top of a Java Doc '.html' Page) truncated.

        Note that the original Java Doc Tool, itself, doesn't always provide the cleanest of pages when the Comments for a Method or Field become very long or intricate. Usually, if HTML of any kind is used in the comments section of a method or field is used, then the Method Summaries or Field Summaries may look awfully skewed.
        See Also:
        summaryRemoveFilter, setSummaryRemoveFilter(Predicate)
        Code:
        Exact Method Body:
        1
         this.summaryRemoveFilter = ALWAYS_FALSE; return this;

      • doNotHiLiteSourceCodeFiles

        public Upgrade doNotHiLiteSourceCodeFiles()
        This will set a filter Predicate that returns FALSE for every Class, Interface or Enum. If this method is used, then none of the Java-Doc Upgraded Pages will have their full Source Code Files HiLited. There is usually a link at the top of the Upgraded Pages that allows a user to click and see the original '.java' source-code.
        See Also:
        hiLiteSourceCodeFileFilter, setHiLiteSourceCodeFileFilter(Predicate)
        Code:
        Exact Method Body:
        1
         this.hiLiteSourceCodeFileFilter = ALWAYS_FALSE; return this;

      • doNotHiLiteFields

        public Upgrade doNotHiLiteFields()
        This will set a filter Predicate that returns FALSE for every Class, Interface or Enum. If this method is used, then none of the Java-Doc Upgraded Pages will have their Field Declarations HiLited.
        See Also:
        hiLiteAllFieldsFilter, setHiLiteAllFieldsFilter(Predicate)
        Code:
        Exact Method Body:
        1
         this.hiLiteAllFieldsFilter = ALWAYS_FALSE; return this;

      • hiLiteConstructors

        public Upgrade hiLiteConstructors()
        Differing from Fields and Methods, constructors in an upgraded Java-Doc Page are not automatically hilited. You need to explicity ask the upgrader to hilite Constructor Bodies. This method will indicate to the upgrader to hilite the Constructor Bodies for all classes and enums that it encounter.

        This will set a filter Predicate that returns TRUE for every Class or Enum. If this method is used, then all of the Java-Doc Upgraded Pages will have their Constructor Bodies HiLited.
        See Also:
        hiLiteAllConstructorsFilter, setHiLiteAllConstructorsFilter(Predicate)
        Code:
        Exact Method Body:
        1
         this.hiLiteAllConstructorsFilter = ALWAYS_TRUE; return this;

      • doNotAddCSSTags

        public Upgrade doNotAddCSSTags()
        This will set a filter Predicate that returns FALSE for every Class, Interface or Enum. If this method is used, then none of the Java-Doc Upgraded Pages will have CSS Tags inserted.

        This will make it impossible to employ any of the CSS Colorizing or Font-Changing features made available by this Upgrader.
        See Also:
        cssTagsFilter, setCSSTagsFilter(Predicate)
        Code:
        Exact Method Body:
        1
         this.cssTagsFilter = ALWAYS_FALSE; return this;

      • setEmbedTagsMapFile

        public Upgrade setEmbedTagsMapFile​(java.lang.String tagIDMapFileName)
        Sets an Embed Tag ID Table using a text file on your file-system.

        You have the ability to insert HTML '<EMBED>' tags into the comments of your source-files, because this Upgrader will replace those HTML elements with the HTML found in the file named by this map. See the image below as an example: Notice that all that has to be provided to the tag is a 'DATA-FIILE-ID'. This 'ID' is mapped to a file-system text-file using this map.

        HTML EMBED Tag Example
        Parameters:
        tagIDMapFileName - This text-file should contain lines of text with "DATA-FILE-ID's" and '.html' File-Name's - each on a separate line.

        The Embed Tags Map for this JAR Build Script (as an example) can be viewed here:

        Embed Tags Map File
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        HELPER.readMapFile(String), setEmbedTagsMap(java.util.Map<java.lang.String, java.lang.String>), embedTagIDTable
        Code:
        Exact Method Body:
        1
2
         Hashtable<String, String> ret = HELPER.readMapFile(tagIDMapFileName);
 return setEmbedTagsMap(ret);

      • setEmbedTagsMap

        public Upgrade setEmbedTagsMap​
            (java.util.Map<java.lang.String,​java.lang.String> tagIDMap)
        Sets an Embed Tag ID Table using a Java java.util.Map<tring, String>. The first Generic String-Parameter of the map is for a 'DATA-FILE-ID', and the second is expected to hold '.html' file-names.
        Parameters:
        tagIDMap - This should map 'DATA-FILE-ID' to an '.html' File-Name.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        UpgradeException.checkFileExistsAndCanAccess(String, String), embedTagIDTable
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
         embedTagIDTable.clear();

 tagIDMap.forEach((String embedTagID, String htmlFileName) ->
 {
     try
     {
         UpgradeException.checkFileExistsAndCanAccess
             (htmlFileName, "External HTML Documentation File to Insert");
     }
     catch (Throwable t)
     {
         ERROR(t,
             "There was an error while attempting to load the ID File for ID: " +
             '[' + C.BCYAN + embedTagID + C.RESET + "]\n" +
             "Attempting to load File:\n" + C.BYELLOW + htmlFileName + C.RESET
         );

         System.exit(0);
     }

     embedTagIDTable.put(embedTagID, htmlFileName);
 });

 return this;

      • setHiLiter

        public Upgrade setHiLiter​(HiLiter hiLiter)
        Tells this Upgrader to use a particular 'HiLiter'. The default HiLiter is used if this method isn't invoked. Replacement HiLiter's are better explained by the HiLiter Functional-Interface
        Parameters:
        hiLiter - This should be any implementation of the 'HiLiter'.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        hiLiter
        Code:
        Exact Method Body:
        1
         this.hiLiter = hiLiter;   return this;

      • retrieveDefaultJDCSSFileFromJAR

        public static java.lang.String retrieveDefaultJDCSSFileFromJAR()
        Returns the contents of the standard JavaDoc Upgrade CSS File as a String.

        IMPORTANT: The CSS file that is loaded is actually stored in a data-file within the Java-HTML JAR file library. This string remains, on disk, in the JAR unless this method is invoked. In order to customize the CSS to your liking, please review the String that is returned by this method. The fonts, colors, and styles that are produced by the default CSS file are the ones used in this documentation page that you are reading right now. These font, color, and style CSS definitions may be changed by retrieving this CSS definition page (as a java.lang.String, and saving that String to a file). Once the standard-issue CSS has been modified to fit your needs, using the new-updated definitions is done by invoking setCustomJDCSSFile(String).

        NOTE: The actual CLASS and ID tags inserted by this tool cannot be changed - only the definitions (fonts, colors, & styles) may be modified. The actual '.css' file retrieved (as a java.lang.String) contains much explanation and commenting for each of the CLASS and ID tags defined on the page. Again, save this String to disk, and look at it. If it looks like some of the definitions could look better, modify them and then pass the updated '.css' file to method setCustomJDCSSFile(String).

        STATIC METHOD: This method may be invoked at any time, it does not require an instance of 'Upgrade' to be running. Reviewing CSS can be complicated, and changing the code 'off-line' is encouraged.

        FINALLY: The documentation for class Colorize also has a detailed explanation for each of the CLASS and ID definitions inserted by this upgrader tool. This class should also be reviewed if the comments and documentation included in the String / file returned by this method are insufficient for understanding what is happening.

        The default CSS File used by this upgrader may be viewed here:

        Default CSS File
        Returns:
        A CSS File which utilizes the added CSS Colorize CLASSES. The actual file is read from disk, and returned as a String.
        See Also:
        LFEC.readObjectFromFile_JAR(Class, String, boolean, Class), setCustomJDCSSFile(String), Colorize, jdCSS
        Code:
        Exact Method Body:
        1
2
         return LFEC.readObjectFromFile_JAR
     (Torello.Data.DataFileLoader.class, "data14.sdat", true, String.class);

      • setCustomJDCSSFile

        public Upgrade setCustomJDCSSFile​(java.lang.String CSSFileAsAString)
        Set's the CSS Definitions file to a custom-made CSS file.

        IMPORTANT: The actual CSS CLASS Names and ID Tag's cannot be changed in this file. The styles, colors, fonts may be modified, added and deleted as needed by the ultimate design-choices. However, there is no way to change CLASS or ID names of the CSS tags that are inserted.

        NOTE: The Upgrader Tool's method retrieveDefaultJDCSSFileFromJAR() will return the complete CSS definition '.css' file. Review that method's documentation for more information. Save that java.lang.String to a file on your file-system, and then update it or modify it to suit your projects design choices. Afterwards, pass that file as a java.lang.String to this method - and your updated CSS style-definitions will be incorporated into the JavaDoc pages produced by this Upgrader Tool.

        AGAIN: The parameter to this method expects the CSS File to be loaded into a String, this method is not requesting a file-name!
        Parameters:
        CSSFileAsAString - This parameter can be used to associate a custom CSS definition file with the javadoc output that is generated. The entire contents of the CSS File as a java.lang.String - must be passed as input to this method.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        jdCSS, retrieveDefaultJDCSSFileFromJAR(), Colorize
        Code:
        Exact Method Body:
        1
         this.jdCSS = CSSFileAsAString; return this;

      • setFaviconFileFormat

        public Upgrade setFaviconFileFormat​(IF faviconFileFormat)
        This is how to request that a favicon be added to all Java Doc Web-Pages. The file-format is just the favicon's image-type (.jpg, .png, etc...)
        Parameters:
        faviconFileFormat - The file-format for the favicon-file.

        NOTE: The favicon file-name must be 'favicon'
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        faviconImageFileName
        Code:
        Exact Method Body:
        1
2
         this.faviconImageFileName = FAVICON_FILE_NAME + '.' + faviconFileFormat.toString();
 return this;

      • printStats

        public Upgrade printStats​(boolean print)
        If you do not want the statistics printed to terminal at the end of the upgrade, pass FALSE to this method. By default, the computed-statistics are printed when the upgrade has finished.
        Parameters:
        print - This informs the Upgrader whether you would like to see the Stats at the end of the upgrade. The default value for this field is TRUE
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        printStats
        Code:
        Exact Method Body:
        1
         this.printStats = print;  return this;

      • setCheckBalance

        public Upgrade setCheckBalance​(boolean checkBalance)
        Turns the HTML balance-checker logic on or off. Read more about balance-checking in the documentation for field checkBalance, or in the class Torello.HTML.Balance. By default, this field is set to 'TRUE'.
        Parameters:
        checkBalance - The value of this parameter can turn the balance checker on or off. The default value of the internal 'checkBalance' flag is TRUE.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        checkBalance
        Code:
        Exact Method Body:
        1
         this.checkBalance = checkBalance; return this;

      • setExtraTasks

        public Upgrade setExtraTasks​
            (java.util.function.Consumer<CommonParamRecord> extraTasks)
        This allows a user to do his own, user-specified tasks to a java-doc vectorized-html page before it is written to disk. The "Extra Tasks" 'Consumer' will receive the same data that all of the primary-operations classes in this Upgrader package receive. To read all of the available datum that is retrieved for each Java Doc Class, Interface & Enumerated-Type, see the class CommonParamRecord.

        NOTE: Somewhat similar to the Doclet feature, when the Upgrader is provided an Extra Tasks, the user may modify the JavaDoc page in any arbitrary way he chooses. The page is passed as a parsed HTML File.

        IMPORTANT: Make sure that any changes made are, indeed, made to the 'fileVec' field of the CommonParamRecord class. Othereise, those changes will not be reflected in the output Java Doc HTML Page.
        Parameters:
        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. Make sure that whatever Consumer is passed performs its modifications to the HTML on the vectorized-HTML field CommonParamRecord.fileVec inside the class CommonParamRecord
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        extraTasks
        Code:
        Exact Method Body:
        1
         this.extraTasks = extraTasks; return this;

      • setPackageSummaryCleaner

        public Upgrade setPackageSummaryCleaner​
            (java.util.function.Consumer<java.util.Vector<HTMLNode>> packageSummaryCleaner)
        Sets the cleaner. This is very simple concept, but it may be complex to implement. Java's 'AI' for putting a one-line or one-sentence summary as a description into the "Summary Pages" for Java Packages is sometimes horribly skewed. This occurs if there is any HTML inside a Java Doc Comment.

        The best way to learn to use this Consumer<Vector> is to try writing a simple that just prints the HTML to the termainl, and see what can be done with it. The size of the problem is limited by how much code-comments you have put into the comment portions of the method's and field's in your source code files.

        Try looking at the default-cleaner for this library. Since there is a Very large amount of documentation and code-comments (since this is actually a code-commenting package), the cleaner is a little difficult to understand - although what it is doing is very easy stuff. The default cleaner is linked below:

        CleanPackageSummaries.defaultCleaner(Vector)
        Parameters:
        packageSummaryCleaner - This should be any lambda or method that will clean the CIET HTML descriptions so they aren't skewed.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        packageSummaryCleaner
        Code:
        Exact Method Body:
        1
         this.packageSummaryCleaner = packageSummaryCleaner;  return this;

      • setPackageFrames

        public Upgrade setPackageFrames​(java.lang.String[] packages,
                                java.lang.String[][] sectionNames,
                                java.lang.String[][][] sectionContents,
                                boolean usesFrames)
        This is a sample of what the input arrays should look like. This is the "Rearrange Frames" class used to build the Java HTML Library. The file is quite long, however, at the end of this class (below), the fields are collated into arrays so that they may be passed to this method.

        Torello.Build.Helper.PackageItems.java
        Parameters:
        packages - The list of packages as a String-Array
        sectionNames - A Two-Dimensional String-Array that is parallel to the previous 'packages' parameter. Each sub-array here should contain the list of section names for the package in the parallel array.
        sectionContents - A Three-Dimensional String-Array. The first dimension is parallel to both of the other two input array-parameters. Each of the sub-two-dimensional arrays merely / simply (this is not rocket-science) contains a list of classes (and interfaces, enum's, exceptions, etc...) that you want inside the "section" identified by the corresponding element of the 'sectionNames'-array.
        usesFrames - By default this method will re-arrange the classes, interfaces, etc... that are listed on the 'package-summary.html' pages. If you have opted to request JavaDoc produce 'package-frame.html' files, pass TRUE to this method, and those files will also be re-arranged
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        Throws:
        ParallelArrayException - If any of these three arrays aren't of equal lengths!
        java.lang.NullPointerException - If any of these arrays contain any 'null' values
        See Also:
        rearrangeFrames
        Code:
        Exact Method Body:
        1
2
3
4
         this.rearrangeFrames = new RearrangePkgFrame.PackageItems
     (packages, sectionNames, sectionContents, usesFrames);

 return this;

      • setSummaryRearrange

        public Upgrade setSummaryRearrange​
            (java.lang.String[] ciets,
             java.lang.String[][] sectionNames,
             FCM[] sections,
             java.util.function.ToIntFunction[] sorters)
        This sets the Summary Section Rearrange Logic. Below is a sample of what the arrays should look like in order for this upgrader to perform such an upgrade. This is the "Rearrange Summaries" list of arrays used to build the Java HTML Library. This file is quite long, but reading might make it easier to understand what actually belongs inside these arrays. At the very end of the class in this link, the arrays are collated so that they may be passed here.

        Torello.Build.Helper.SummRearrange.java
        Parameters:
        ciets - The list of classes, interfaces and enumerated-types having a summary section to be rearranged during the upgrade.
        sectionNames - This lists the names into which the table-rows should be sorted for each of the ciets.
        sections - For eachj of the CIET's passed in the first array, this identifies whether the particularly summary to be re-arranged is a Field, Constructor or Method.
        sorters - These sort the FCM's.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        Throws:
        ParallelArrayException - If any of these three arrays aren't of equal lengths!
        java.lang.NullPointerException - If any of these arrays contain any 'null' values
        See Also:
        summaryItems
        Code:
        Exact Method Body:
        1
2
3
4
         this.summaryItems = new RearrangeSummaries.SummaryItems
     (ciets, sectionNames, sections, sorters, rootSourceFileDirectory);

 return this;

      • upgrade

        public Stats upgrade​(StorageWriter sw)
        After all parameters have been set with this "JavaDoc Upgrader" (builder)... this method should be invoked to do the processing. This runs the upgradeer for all Java Doc '.html' Files.
        Parameters:
        sw - This is the log.
        Returns:
        This returns the statistics computed for the upgrade process. See the class Stats for more information. The stats are also printed to the output-stream (StorageWriter) at the end of the upgrade / build process.
        Throws:
        UpgradeException - An unchecked exception. (RuntimeException)
        JavaDocError - If there any I/O errors, or other problems. Review the detailed messages provided - and possibly the Throwable.getCause().
        Code:
        Exact Method Body:
        1
2
3
4
5
6
         try
     { upgradeWithThrows(sw); }
 catch (Throwable t)
     { ERROR(t, "There was an error while running the Upgrader."); }

 return stats;

      • run

        public void run​(java.lang.String jdFileName,
                StorageWriter sw)
        This runs the Java-Doc Upgrade Mechanism for a single Java Doc '.html' file
        Parameters:
        jdFileName - This is the File-System File-Name of the Java-Doc HTML Web-Page File.
        sw - This is a log. This parameter may not be null. If you do not require any log information, then simply set StorageWriter.sysOut to FALSE.
        Throws:
        UpgradeException - An unchecked exception. (RuntimeException)
        JavaDocError - If there any I/O errors, or other problems. Review the detailed messages provided - and possibly the Throwable.getCause().
        Code:
        Exact Method Body:
          1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
         String file = null;

 // *****************************************
 // ********* Collect the Garbage ***********
 // *****************************************

 if ((++gcCount % 7) == 0) { System.gc(); }

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

 if (VERBOSE_PRINT_STEPS) sw.println(
     "\n\n**************************************************************************" +

     '\n' + StringParse.rightSpacePad("Free Memory Available:", 35) +
         C.BBLUE + freeMem  + C.RESET +

     '\n' + StringParse.rightSpacePad("Total Memory Available:", 35) +
         C.BBLUE + totalMem + C.RESET
 );

 // *****************************************
 // *********** Load JavaDoc File ***********
 // *****************************************

 sw.println
     (StringParse.rightSpacePad("Loading File:", 35) + C.BYELLOW + jdFileName + C.RESET);

 try
     { file = FileRW.loadFileToString(jdFileName);  }
 catch (Throwable t) // (IOException ioe)
     { ERROR(t, "Failed to load File: " + C.BYELLOW + jdFileName + C.RESET); }

 Vector<HTMLNode> fileVec = HTMLPage.getPageTokens(file, false);

 // *****************************************
 // ********** Get File Information *********
 // *****************************************

 // Retrieves the CIET Name with Package Information, and the simple "File-Name"
 Ret2<String, String> r2 = HELPER.getFullNameAndSourceFileName(fileVec);

 String cietFullName    = r2.a;
 String srcCodeFileName = rootSourceFileDirectory + r2.b;
 String dotDots         = StringParse.dotDots(jdFileName, rootJavaDocDirectory, FSEP);

 sw.println(
     StringParse.rightSpacePad("Fully-Qualified Name:", 35) +
         C.BYELLOW + cietFullName + C.RESET + '\n' +

     StringParse.rightSpacePad("Built from Source-File:", 35) +
         C.BYELLOW + srcCodeFileName + C.RESET + '\n' +

     StringParse.rightSpacePad("Relative-URL String:", 35) +
         C.BYELLOW + dotDots + C.RESET
 );

 // *****************************************
 // *********** JavaDocHTMLFile *************
 // *****************************************

 JavaDocHTMLFile jdhf = null;

 try
     { jdhf = new JavaDocHTMLFile(fileVec, jdFileName, sw); }
 catch (Throwable t) // (IOException ioe)
     { ERROR(t, "Cannot parse Java Doc HTML File:\n" + C.BYELLOW + jdFileName + C.RESET); }

 String listJDHF = StrCSV.toCSV(jdhf.getGenericParameters(), true, true, null);

 sw.println(
     StringParse.rightSpacePad("Parsed JavaDoc '.html':", 35) +
     "Name [" +      C.BYELLOW + jdhf.name +         C.RESET + "], " + 
     "Package [" +   C.BYELLOW + jdhf.packageName +  C.RESET + "], " +
     "CIET [" +      C.BYELLOW + jdhf.ciet +         C.RESET + "]"   +
     ((listJDHF.length() > 0) 
         ? ('\n' + StringParse.rightSpacePad("Generic-Parameters Found: ", 35) + listJDHF) 
         : "")
 );

 // *****************************************
 // ********* JavaSourceCodeFile ************
 // *****************************************

 String                  srcCodeAsStr    = null;
 JavaSourceCodeFile      jscf            = null;

 try
     { srcCodeAsStr = FileRW.loadFileToString(srcCodeFileName); }
 catch (Throwable t) // (IOException ioe)
 {
     ERROR(t,
         "Unable to load file:\n" + C.BYELLOW + srcCodeFileName + C.RESET + "\n" +
         "Currently Processing JavaDoc HTML Page:\n" + C.BYELLOW + jdFileName + C.RESET
     );
 }

 jscf = JavaSourceCodeFile.parse(srcCodeAsStr, srcCodeFileName, jdhf.name, jdhf.ciet);

 String listJSCF = StrCSV.toCSV(jscf.getGenericParameters(), true, true, null);

 sw.println(
     StringParse.rightSpacePad("Parsed Source '.java':", 35) +
     "Name [" +      C.BYELLOW + jscf.name +         C.RESET + "], " + 
     "Package [" +   C.BYELLOW + jscf.packageName +  C.RESET + "], " +
     "CIET [" +      C.BYELLOW + jscf.ciet +         C.RESET + "]"   +
     ((listJSCF.length() > 0) 
         ? ('\n' + StringParse.rightSpacePad("Generic-Parameters Found: ", 35) + listJSCF) 
         : "")    
 );

 // *****************************************
 // ********* Print Parser Find's ***********
 // *****************************************

 sw.println(
     StringParse.rightSpacePad("'.html' File Parser Found:", 35) +
     '[' + C.BBLUE + StringParse.zeroPad(jdhf.numFields())       + C.RESET + "] Fields, " +
     '[' + C.BBLUE + StringParse.zeroPad(jdhf.numConstructors()) + C.RESET + "] Constructors, " +
     '[' + C.BBLUE + StringParse.zeroPad(jdhf.numMethods())      + C.RESET + "] Methods"
 );

 sw.println(
     StringParse.rightSpacePad("'.java' File, JavaParser Found:", 35) +
     '[' + C.BBLUE + StringParse.zeroPad(jscf.numFields())       + C.RESET + "] Fields, " +
     '[' + C.BBLUE + StringParse.zeroPad(jscf.numConstructors()) + C.RESET + "] Constructors, " +
     '[' + C.BBLUE + StringParse.zeroPad(jscf.numMethods())      + C.RESET + "] Methods"
 );

 sw.println("**************************************************************************");

 // *****************************************
 // ********* Main Operations Setup *********
 // *****************************************

 // Every single one of the "Primary Operations" (below, there are TEN of them) basically
 // take the same (rather long) list of parameters.  This silly little class just
 // encapsulates them all into a single-parameter... No More, No Less!

 CommonParamRecord pr = new CommonParamRecord(
     fileVec, cietFullName,
     jscf, jdhf,
     jdFileName, srcCodeFileName, hiLiter,
     embedTagIDTable,                                // This one is only used by EmbedTags
     srcCodeAsStr, dotDots, faviconImageFileName,    // Only used by HiLiteSrcCodeFile
     VERBOSE_PRINT_STEPS ? sw : null, stats
 );

 boolean hlscf = (hiLiteSourceCodeFileFilter == null) ||
     hiLiteSourceCodeFileFilter.test(cietFullName);

 boolean sr = (summaryRemoveFilter == null) ||
     summaryRemoveFilter.test(cietFullName);

 boolean hlf = (hiLiteAllFieldsFilter == null) ||
     hiLiteAllFieldsFilter.test(cietFullName);

 boolean hlm = (hiLiteAllMethodsFilter == null) ||
     hiLiteAllMethodsFilter.test(cietFullName);

 boolean csst = (cssTagsFilter == null) ||
     cssTagsFilter.test(cietFullName);

 boolean hlc = (hiLiteAllConstructorsFilter != null)  &&
     hiLiteAllConstructorsFilter.test(cietFullName);

 // *****************************************
 // ************ Main Operations ************
 // *****************************************

 int numHiLitedFields        = 0, numHiLitedMethods  = 0;
 int numHiLitedConstructors  = 0, numHiLitedDivs     = 0;

 if (hlscf) HiLiteSrcCodeFile.run(pr);
 else sw.println(
     "HiLiteSourceCodeFile.run(...)" + C.RESET + "\n\t" +
     C.BBLUE + " was not called, as per request." + C.RESET
 );

 if (sr) CleanSummaries.removeAllDescriptionsFromSummaries(pr);
 else sw.println(
     "CleanSummaries.removeAllDescriptionsFromSummaries(...)" + "\n\t" +
     C.BBLUE + " was not called, as per request." + C.RESET
 );

 EmbedTag.run(pr);

 numHiLitedDivs = HiLiteDividers.run(pr);

 if (hlf)
     numHiLitedFields = HiLiteFields.run(pr);
 else sw.println(
     "HiLiteFields.run(...)" + C.RESET + "\n\t" +
     C.BBLUE + " was not called, as per request." + C.RESET
 );

 if (hlm)
     numHiLitedMethods = HiLiteMethods.run(pr);
 else sw.println(
     "HiLiteMethods.run(...)" + C.RESET + "\n\t" +
     C.BBLUE + " was not called, as per request." + C.RESET
 );

 SkewedParameters.run(pr);

 if (csst)
     Colorize.run(pr);
 else sw.println(
     "Colorize.run(...)" + C.RESET + "\n\t" +
     C.BBLUE + " was not called, as per request." + C.RESET
 );

 // The default is to skip "HiLiteConstructors" - so, therefore, no message is needed
 if (hlc)
     numHiLitedConstructors = HiLiteConstructors.run(pr);

 sw.println("Other:");

 if (summaryItems != null) RearrangeSummaries.run(pr, summaryItems);

 if (pr.jscf.staticFunctionalAnnotation) StatelessClasses.run(pr);

 Convenience.checkForConvenienceMethods(fileVec, sw);
 Convenience.checkForConvenienceConstructors(fileVec, sw);

 stats.run(pr, numHiLitedMethods, numHiLitedConstructors, numHiLitedFields, numHiLitedDivs);

 // *****************************************
 // ************* HTML <HEAD> ***************
 // *****************************************

 Features.insertCSSLink(fileVec, dotDots + JAVA_DOC_CSS_FILE_NAME);
 sw.println(
     "\t" + StringParse.rightSpacePad("Inserted: CSS-Definitions Relative-Link:", 45) +
      "'" + C.BYELLOW + dotDots + JAVA_DOC_CSS_FILE_NAME + C.RESET + "' "
 );

 if (faviconImageFileName != null)
 {
     Features.insertFavicon(fileVec, dotDots + faviconImageFileName);
     sw.println(
         "\t" + StringParse.rightSpacePad("Inserted Favicon Relative-Link:", 45) +
         "'" + C.BYELLOW + dotDots + faviconImageFileName + C.RESET + "'"
     );
 }
 else sw.println
     ("\tFavicon Relative-Link " + "\n\t" + C.BBLUE + "was not inserted, as per request.");

 if (extraTasks != null) extraTasks.accept(pr);

 // *****************************************
 // *********** HTML Tag Balance ************
 // *****************************************

 if (checkBalance)
 {
     Hashtable<String, Integer> b = Balance.checkNonZero(Balance.check(fileVec));

     if (b.size() == 0) sw.println
         ("Balance-Report:\n\tAll non-singleton tags are balanced.");
     else
         ERROR(
             new BalancedHTMLException
                 ("File: " + jdFileName + " had unbalanced HTML tags.", b),
             "HTML Balance Error while processing file:\n" + C.BYELLOW + jdFileName + C.RESET
         );
 }

 // *****************************************
 // ****** ReWrite JDFile File to Disk ******
 // *****************************************

 sw.println("Re-Writing File Back to Disk: " + C.BYELLOW + jdFileName + C.RESET);

 try
     { FileRW.writeFile(Util.pageToString(fileVec), jdFileName);  }
 catch (Throwable t) // (Exception e)
     { ERROR(t, "Failed to write File: " + C.BYELLOW + jdFileName + C.RESET); }

 // *****************************************
 // ************ Write log data *************
 // *****************************************

 if (logFile != null)
 {
     String temp = C.toHTML(sw.getString(), true, true, true).replace("\t", "        ");
     logFile.accept(temp + "\n\n");
     sw.erase();
 }

      • main

        public static void main​(java.lang.String[] argv)
                 throws java.lang.Exception
        SIMPLIFIED COMMAND LINE OPERATION.

        This method contains a section of the contents of the Java-HTML library build-script. All of the lines are commented out, but the JavaDoc Upgrade Tool's use is exhibited. This is a 'main' method, so it therefore may be run from the command-line by calling the "Upgrade" tool's class at the command line. It will read the first agrument and the second argument as:

        1. argv[0]: (REQUIRED) The output java-doc directory

        2. argv[1]: (OPTIONAL) The HiLiteMe Cache Directory


        REMEMBER: The most important point is that the actual javadoc utility must have already been invoked on the source-code that is to be hilited before the upgrade tool can be invoked! Below is the command line for building the Java-HTML libraries initial javadoc pages (before they are upgraded by this tool.)

         1
 2
 3
 4
 5
 6
 7
 8
 9
10
        public static final String[] jdCommand =
{
    "javadoc",
        "Torello.Java", "Torello.Java.Additional", "Torello.Java.Function", 
        "Torello.HTML", "Torello.HTML.NodeSearch", 
        "Torello.HTML.Tools.JavaDoc", "Torello.HTML.Tools.NewsSite", "Torello.HTML.Tools.Images",
        "Torello.Languages", "Torello.REST"
        "-d", "javadoc", "-docfilessubdirs", "-linksource", "-docencoding", "UTF-8",
        "-charset", "UTF-8", "--allow-script-in-comments", "-sourcetab", "4"
};


        CACHE-INITIALIZING: In order to build a "HiLite.ME Cache", or to clear an over-used cache which after much use could be emptied - all that is needed to is to make sure that the directory where the cache is to be placed does not exist and has been deleted. When the specified "HiLite Cache Directory" has been fully removed from the file-system, the Upgrade Tool will build an empty CACHE, and begin to save the hilited code (retrieved from HiLite.ME) in the local file-system so that the same code does not need to be processed again and again. When the directory has been fully erased (and removed, completely), the Upgrade Tool will build a new 'HILITED_STRINGS_HASH_CODE.ts' file and also create the necessary directory to store the saved-files in that directory.

        EXAMPLE USE: While looking for a good java-based spell checker, this package came up. After downloading the source-code files to the local file-system, the following two commands produced an "Upgraded Java-Doc" experience. The first line below will run the standard javadoc utility, and leave the contents in directory "~/javadoc/". The second command will "Upgrade" the tool by inserted code-hiliting, adding CSS Names, and adding a favicon. Remember, to alter the colors, the CSS file that's left in the output directory, "~/javadoc/JavaDoc.css" can be modified and altered to make the colors, shapes, etc... in line with the project.

        UNIX or DOS Shell Command:
        cloudshell:~$ cloudshell:~$ javadoc com.inet.jortho com.inet.jorthodictionaries -d javadoc -docfilessubdirs -linksource -docencoding "UTF-8" -charset "UTF-8" --frames --allow-script-in-comments -sourcetab 4 cloudshell:~$ java Torello.HTML.Tools.JavaDoc.Upgrade javadoc/ jdcache/
        Parameters:
        argv - This is the argument received from the command line.
        Throws:
        java.lang.Exception
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
         StorageWriter sw = new StorageWriter();
 Upgrade upgrader = new Upgrade(argv[0], "");

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

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

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

     Cache CACHE = new Cache(argv[1]);
     upgrader.useHiLiteServerCache(CACHE).upgrade(sw);
     CACHE.persistMasterHashToDisk();
 }
 else
     System.out.println("Failed, expected one or two arguments");