Class Upgrade

  • public class Upgrade
extends java.lang.Object
    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.

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

    Currently, This App Only Upgrades Java 11 Java-Doc HTML, and Earlier.

    Building an Upgrader 'JDVersion' Configuration-Class will not be too much work (a few weeks, to a month). The pages you are currently reading right now were successfully upgraded from HTML Files generated by the Java-Doc Tool released with Java 11 (LTS).

    What follows is an example where some of the initializer fields for this upgrader are actually used.

    Example:
        // An example use of a CIET/Type Canonical-Name Predicate to decide Which Classes/Types should
    // undergo have their FIELD's being HiLited (and which Types shouldn't show HiLited Fields)

    final Predicate<Object> dontHiLiteTheFields = StrFilter.strListREJECT_NOIOE
        ("Torello/Build/TXT/SkipAllFields.txt", false);

    new Upgrade                     ("javadoc/", "")
        .setLogFile                 ("log.html")
        .setFaviconFileFormat       (Torello.HTML.Tools.Images.IF.JPG)
        .setEmbedTagsMapFile        ("Torello/Build/global-external-html-ids.properties")
        .useHiLiteServerCache       ("cache/")
        .setHiLiteAllFieldsFilter   (dontHiLiteTheFields)
        .upgrade                    ();


    • Constructor Detail

      • Upgrade

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade​(java.lang.String rootJavaDocDirectory,
               java.lang.String... rootSourceFileDirectories)
        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.
        rootSourceFileDirectories - This is the location where the '.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 '.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 'getCause()' method of the exception will provide more details of the specific error that occurred.

    • Method Detail

      • upgrade

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Stats upgrade()

        START THE UPGRADE, HERE


        After all parameters have been set with this configuration-builder class (Upgrade) ... this method needs to be invoked to start the processing. This runs the upgrader for all Java Doc generated '.html' Files.

        The log-file that may be set with this class is where printed character data is later stored / saved so that it may be reviewed after this upgrade completes. The printed data is minimal, unless 'Verbose Mode' has been requested.
        Returns:
        This returns the statistics computed for the upgrade process. See class Stats for more information. A complete listing of the information contained by the tables in a 'Stats' instance may be viewed by clicking the 'Stats' link at the top-right of this page.

        If the Upgrade-Process had unrecoverable errors, null is returned.

      • main

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void main​(java.lang.String[] argv)
                 throws java.lang.Exception

        Command Line Operation


        The first and second Command Line Argument's are as below

        1. argv[0]: (REQUIRED) The output java-doc directory
        2. argv[1]: (OPTIONAL) The HiLiteMe Cache Directory


        Running 'javadoc' First:
        The actual 'javadoc' Utility, itself (the one provided by Oracle), must first be invoked on the source-code that is to be hilited before the Upgrade-Tool can be used!

        Example:
        While looking for a good Java-Based Spell-Checker, this package came up. After downloading the source-code, the commands were able to generate 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 pages that were just generated - inserting Code-HiLiting, adding CSS-Names (for a better CSS Look-And-Feel), and (of course) adding a favicon.

        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.JavaDoc.Upgrade javadoc/ jdcache/
        Parameters:
        argv - This is the argument received from the command line.
        Throws:
        java.lang.Exception

      • setRemoveAllDetailsFilter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setRemoveAllDetailsFilter​
            (Entity entity,
             java.util.function.Predicate<? super java.lang.String> cietCanonicalNameFilter)
        Requests that the entire HTML Details-Section for a particular Entity/Member Kind (for instance: Method's, Field's or Constructor's etc...) be removed in entirety.

        There are Java Doc pages that, on occasion, might be more readable without extensive detail information. If this filter returns TRUE for any class, interface, enum, annotation or record (CIET) - all 'Details' for that entity are removed.

        By default this filter-predicate is inactive. It can be used to remvoe all details sections present on a Java Doc page.

        Use in Java-HTML:
        In the Java HTML JAR library, most of the search classes inside the package Torello.HTML.NodeSearch package do not contain any details sections. The methods are very repetitive, and generally resemble the types of functions that assembly languages offer.

        Since a detailed description of those methods (and particularly all of their parameters) is offered at the top of those classes, a redundant-looking detail section is elmininated by using this very Filter-Predicate.
        Parameters:
        entity - Specifies which HTML Detail-Section to remove.
        cietCanonicalNameFilter - The file-name filter. This Predicate needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

        It is usually very easy to provide a list of Canonical Type-Names - A Class-Name that includes the Package-Name and even any Container-Classes in which it resides - to a StrFilter method. There are many "Accept" and "Reject" methods in that class which would take a list of CIET/Type Names.

      • setHiLiteAllDetailsFilter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setHiLiteAllDetailsFilter​
            (Entity entity,
             java.util.function.Predicate<? super java.lang.String> cietCanonicalNameFilter)
        Requests that all HTML Details be HiLited for a particular Entity/Member Kind (for instance: Method's, Field's or Constructor's etc...)

        Default Settings:
        Entity Default Setting
        Method Bodies HiLited
        Field Declarations HiLited
        Constructor Bodies Not HiLited
        Enum-Constant Declarations Not HiLited
        Annotation Element Definitions HiLited

        The filter-parameter ('cietCanonicalNameFilter') that needs to be passed here is just a Java Predicate<String>. This Predicate receives the Fully-Qualified (Canonical) Class-Name of a Java CIET/Type (Class, Interface, Enumerated-Type etc...). '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 Detail-Source HiLited, and FALSE if the Upgrader should skip hiliting the source for this CIET.

        Using a StrFilter:
        If you keep a short '.txt' file that just lists the classes you do or do not 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

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

        HiLited Field Declaration
        Parameters:
        cietCanonicalNameFilter - The file-name filter. This Predicate needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

        It is usually very easy to provide a list of Canonical Type-Names - A Class-Name that includes the Package-Name and even any Container-Classes in which it resides - to a StrFilter method. There are many "Accept" and "Reject" methods in that class which would take a list of CIET/Type Names.

      • setSummaryRemoveFilter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setSummaryRemoveFilter​
            (java.util.function.Predicate<? super java.lang.String> cietCanonicalNameFilter)
        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.

        Default Setting:
        The default configuration for this process is that this Upgrade Tool will 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. If you can remember that the Summary-Section imports the first sentence of the Description-Portion of a Detail-Section, it is possible to make the Summary-Sentences look all right.

        However, when this is neglected, for just about anything but the most trivial of comments explanations, the JavaDoc Logic will not produce a nice enough looking 'Summary Description' to be useable. Therefore, the signature, by itself, is often sufficient.

        Using a StrFilter:
        If you keep a short '.txt' file that just lists the classes you do or do not 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:
        cietCanonicalNameFilter - The file-name filter. This Predicate needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

        It is usually very easy to provide a list of Canonical Type-Names - A Class-Name that includes the Package-Name and even any Container-Classes in which it resides - to a StrFilter method. There are many "Accept" and "Reject" methods in that class which would take a list of CIET/Type Names.

      • setHiLiteSourceCodeFileFilter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setHiLiteSourceCodeFileFilter​
            (java.util.function.Predicate<? super java.lang.String> cietCanonicalNameFilter)
        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.

        Using a StrFilter:
        If you keep a short '.txt' file that just lists the classes you do or do not 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:
        cietCanonicalNameFilter - The file-name filter. This Predicate needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

        It is usually very easy to provide a list of Canonical Type-Names - A Class-Name that includes the Package-Name and even any Container-Classes in which it resides - to a StrFilter method. There are many "Accept" and "Reject" methods in that class which would take a list of CIET/Type Names.

      • setCSSTagsFilter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setCSSTagsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietCanonicalNameFilter)
        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.

        By default, this filter is set to 'Always On' - meaning all Java-Doc Web-Pages will have CSS ID and CLASS Attributes 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.

        Using a StrFilter:
        If you keep a short '.txt' file that just lists the classes you do or do not want hilited, you may load that '.txt' file into a Java Predicate using either:



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

        CSS Tags

        Default '.css' File
        The default CSS File used by this upgrader may be viewed here:

        Default CSS File
        Parameters:
        cietCanonicalNameFilter - The file-name filter. This Predicate needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

        It is usually very easy to provide a list of Canonical Type-Names - A Class-Name that includes the Package-Name and even any Container-Classes in which it resides - to a StrFilter method. There are many "Accept" and "Reject" methods in that class which would take a list of CIET/Type Names.

      • setValidateHTMLFilter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setValidateHTMLFilter​
            (java.util.function.Predicate<? super java.lang.String> cietCanonicalNameFilter)
        This sets the HTML Validation Filter. This filter accepts the name of a class-file, and must return TRUE or FALSE, depending upon whether he would like the HTML Validated for a particular Java Doc File.

        The Predicate<String> passed to this field should either accept or reject a class-file, based on its class-name.

        By default, all class-files are passed through the validating HTML processor.

        This filter allows you to turn off HTML Validation for some or all of the Class-Files in your Upgrade. HTML Validation can be an invaluable resources when debugging and fixing your Documentation; however there might be situations where less-than-valid HTML is needed. For instance, some packages have developers who refuse to close their <LI> elements, or perhaps their <TD>'s

        Note that there is also a "Check Balance" flag that can be set with this Upgrade Configuration-Class. When this flag is set to FALSE its value 'takes precedence' over anything that is returned by the validateHTMLFilter. To see this in action, view the example below:

        Example:
        Predicate<String> myClassesFilter = (String fullClassName) ->
    fullClassName.startsWith("org.company.tests") ||
    fullClassName.startsWith("com.consulting.optimizer");

new Upgrade("javadoc", "src/main/java")
    .setCheckBalance(false)
    .setValidateHTMLFilter(myClassesFilter)
    ...
    .upgrade()


        Configuration Precedence:
        Because there is a call to the Configuration-Method setCheckBalance(false), the subsequent call to setValidateHTMLFilter is no different than a "No Op". This configuration will simply have no effect on the final processing.

        The Check-Balance setting supersedes the results of this Filter-Predicate, and when it is false, this Predicate is effectively ignored.

        <EMBED>-Tag HTML Files:
        The results of this Predicate do not affect the validation of Externally-Linked <EMBED CLASS='external-html'> files. If you would like to avoid validating those files, you must request that the Check-Balance Flag be set to FALSE.

        All external-html files (imported with the EMBED-tag) are checked for valid HTML before the Upgrade Process even starts.
        Parameters:
        cietCanonicalNameFilter - The file-name filter. This Predicate needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

        It is usually very easy to provide a list of Canonical Type-Names - A Class-Name that includes the Package-Name and even any Container-Classes in which it resides - to a StrFilter method. There are many "Accept" and "Reject" methods in that class which would take a list of CIET/Type Names.

      • setVerbosityLevel

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setVerbosityLevel​(Verbosity verbosity)
        Accepts an instance of Verbosity. This configures the output-text behavior of the Upgrade-Tool once processing begins.

        The table below should delineate the different output behaviors which may be selected using this Configuration Method.
        Verbosity-SettingUpgrade Processing Text Output
        Silent All Error Output is still printed to the terminal. A single period '.' is emitted at the beginning of processing a new Java Package.
        Quiet All Error Output is still printed to the terminal. Messaging is greatly abbreviated, as most notices are reduced a single period '.' character.
        Normal Normal, textual operations.
        Verbose Extra amounts of notices are appended after processing each Java-Doc HTML File.
        Parameters:
        verbosity - One of the four available Verbosity constants.

      • setLogFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setLogFile​(java.lang.Appendable logFile)
        When the Upgrader outputs text to Terminal, that text may be stored into an internal buffer. That buffer's information will be duplicated to the Appendable instance provided to this method.

        Essentially, Log information may be sent and saved anywhere, using this parameter. As text output is sent the internal Messager instance, this instance of Appendable may be used to duplicate that output so that log data is saved to a file (or any mechanism, of your chossing)) for reviewing the output at a later time.

        In normal mode, the upgrader produces a reasonable amount of text-output; however, in verbose-mode quite a bit of text is sent to the terminal.
        Parameters:
        logFile - An Appendable to be used for backing-up / saving Log-Writes.

      • setLogFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setLogFile​(java.lang.String logFileName)
        When the Upgrader outputs text to Terminal, that text may be stored into an internal buffer. That buffer's information will be duplicated and written to the Text-File specified by this method's input parameter.

        As text output is sent the internal Messager instance, this file will duplicate the output so that log data is saved to a file for reviewing the output at a later time.

        In normal mode, the upgrader produces a reasonable amount of text-output; however, in verbose-mode quite a bit of text is sent to the terminal.
        Parameters:
        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 Also:
        UpgradeException.checkFileIsWriteable(String, String, String)

      • setProjectGlobalEmbedTagsMapFile

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setProjectGlobalEmbedTagsMapFile​
            (java.lang.String tagIDMapFileName)
        Sets a Project Global Embed Tag ID Map 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


        File Contents:
        This text-file should contain lines of text with "DATA-FILE-ID's" and '.html' File-Name's - each on a separate line.

        Java-HTML JAR 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 JAR-Library's Build Script may be viewed below, as an example. This is an exhaustive list of all Global, Externally-Linked, HTML Pages for the Java HTML library.

        Global Embed Tags Map File
        Parameters:
        tagIDMapFileName - A Java '.properties' File-Name mapping File-ID's to Files.
        Throws:
        UpgradeException - If there are any problems that occur while loading the file

      • setProjectGlobalEmbedTagsMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setProjectGlobalEmbedTagsMap​
            (ReadOnlyMap<java.lang.String,​java.lang.String> tagIDMap)
        Sets the Project Global Embed Tag ID Map 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.

        This stores the 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 field holds the "Project" Global Embed Tag ID's." This upgrader also provides a means of saving package-specific external HTML files inside the source-code directory used by any Java Package. For instance, for Package "Torello.HTML", Package-Local HTML files are saved in directory Torello/HTML/upgrade-files/external-html/. There is also a Package-Local ID==>FileName Map. That file should be saved in a file named 'external-html-ids.properties', using a standard Java Properties file format.

        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.

        The Upgrader will automatically converts all HTML <EMBED>-Tags into the actual HTML that is inside the file listed in the external-documentation file you have created for it.

        What EMBED-Tags 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

        Java-HTML JAR 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 JAR-Library's Build Script may be viewed below, as an example. This is an exhaustive list of all Global, Externally-Linked, HTML Pages for the Java HTML library.

        Global Embed Tags Map File
        Parameters:
        tagIDMap - This should map a 'DATA-FILE-ID' to an '.html' File-Name

      • useHiLiterCache

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade useHiLiterCache​(java.lang.String hiLiterCacheDirectoryName)
        Configures the HiLiter to use the Default HiLiter, and use the provided Cache-Directory as the location for Caching HiLited HTML-Files.
        Parameters:
        hiLiterCacheDirectoryName - The name of the File-System Directory which has previously saved HiLited HTML-Files.

        NOTE: If this is the first time using this Cache Directory, and it doesn't exists yet, this directory will be created, and future Upgrade instances will save & cache HiLited-Source HTML to this directory.

      • setHiLiter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setHiLiter​(HiLiter hiLiter)
        Tells this Upgrader to use a particular 'HiLiter'. The default HiLiter will be used if this method isn't invoked.

        Read the interface HiLiter for details about implementing the interface.
        Parameters:
        hiLiter - Any valid implementation of the HiLiter interface

      • retrieveDefaultCSSFilesFromJAR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static CSSFiles retrieveDefaultCSSFilesFromJAR()
        Returns the contents of the standard JavaDoc Upgrade CSS File as a String.

        Lazy-Loading:
        The CSS file that is loaded is actually stored in a data-file within the Java-HTML JAR-File. This String remains, on disk, in the JAR unless this method is invoked.

        Customizing 'JavaDoc.css'
        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).

        CSS Class & ID Names:
        The actual CSS CLASS and ID Tag's cannot be changed in this file. The styles, colors, fonts may be modified (and even deleted or augmented as needed) to follow any and all necessary design-choices.

        However, there is no way to change CLASS or ID names of the CSS-Tags that are inserted by the Java-Doc Tool. There is also no way to change the names of Clases or ID's that were originally generated by the actual 'javadoc' Tool either.

        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.

        This Method is 'static'
        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. You may edit the file at your leisure, and when finished use on subsequent Source-Builds.

        The documentation for class CSSTags 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.
        Returns:
        All Java-Doc Upgrader '.css' Files
        See Also:
        setCustomCSSFiles(CSSFiles)

      • setCustomCSSFiles

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setCustomCSSFiles​(CSSFiles cssFiles)
        Set's the CSS Definitions file to a custom-made CSS file.

        CSS Class & ID Names:
        The actual CSS CLASS and ID Tag's cannot be changed in this file. The styles, colors, fonts may be modified (and even deleted or augmented as needed) to follow any and all necessary design-choices.

        However, there is no way to change CLASS or ID names of the CSS-Tags that are inserted by the Java-Doc Tool. There is also no way to change the names of Clases or ID's that were originally generated by the actual 'javadoc' Tool either.

        Default '.css' File:
        retrieveDefaultCSSFileFromJAR will return the complete default '.css' Definition-File. Review that method's documentation (and its String-Output) for more information about the original / default '.css' File.

        Simply invoke retrieveDefaultCSSFileFromJAR, and save the String that it returns to a file on your File-System. You may update & modify that file, making any changes that are necessary, to accomodate your Project's Design-Choices.

        Afterwards, pass that file as a String to this method - and your updated CSS style-definitions will be incorporated into the JavaDoc pages produced by this Upgrader Tool.

        File-Contents:
        The parameter to this method expects the CSS File, itself, to be loaded in entiretiy into a String, and passed.

        This method is not requesting a file-name!

        The File-Contents that are passed to this method will be written to a file named 'JavaDoc.css'. This file will be copied to the Root Java-Doc Root-Directory by the Upgrader.

        A link to this CSS File will be inserted into each and every Java-Doc Page that is updated. This allows every Web-Page in your Documentation File-Tree to use this CSS File.

        Viewing the Default Files:
        The default CSS Files may be viewed here:

        Upgrader Default-FileFile-Contents Explanation
        Original-Widgets.css CSS Rules & Designs that are to be applied Java-Doc Page Widgets that are inserted by the actual Sun / Oracle 'javadoc', not by any of the Ugrader Logic or Routines.
        Upgrader-Widgets.css CSS Rules & Designs to be applied to Java-Doc Widgets that have been created and inserted by the Upgrader Tool.
        User-Accessories.css CSS Rules & Designs that are used in conjunction, only, with Widgets that are manually placed onto Java-Doc Pages by the user. If the end user does not actually add any of these widgets, then the rules on the CSS Page will not be used.
        Pygments.org.css CSS Rules & Designs that are applied to any & all Page Syntax HiLiting Segments.
        List-Frames.css CSS Rules that are applied on 'package-frame.html' and 'overview-frame.html' Files.
        NO DEFAULT FILE CSS Rules, provided by the user / programmer. Generally to be used with User-Supplied & User-Created HTML-Widgets.
        Parameters:
        cssFiles - All Java-Doc Upgrader '.css' Files
        See Also:
        retrieveDefaultCSSFilesFromJAR()

      • retrieveDefaultJSFileFromJAR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String retrieveDefaultJSFileFromJAR()
        There is an (extremely small / limited) '.js' (Java-Script) File that is copied to the output 'javadoc/' directory.
        Returns:
        The entire contents of the '.js' File (read from disk), returned as a String.

      • 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...).

        When this method is invoked, it requests that an HTML Favicon Link be inserted into each Java-Doc Documentation Web-Page. A Favicon is a small graphical image that appears in the top corner of Web-Page tabs when viewing the page.

        Favicon File-Name:
        The Favicon's File-Name must be 'favicon' - followed by the three-letter or four-letter extension of the File's Type. For instance, if IF.PNG were passed to this method, it would indicate that the Favicon Image-File has the name 'favicon.png'.

        Copy the File:
        After an Upgrade has completed, it is the User's Responsibility to actually copy the Favicon Image-File, itself, into the Java-Doc Root-Directory. If the Image-File isn't copied into the Java-Doc Directory, Web-Browsers won't actually be able to show the Favicon-Image on these Java-Doc Web-Pages.

        HTML <LINK> Tag
        When the image-type file-extension is set, an HTML Link-Tag will be inserted, as below:

        <LINK REL='icon' TYPE='image/jpg' HREF='../favicon.jpg' />'

        This Tag will be inserted into each page of the Java-Doc Upgraded Pages.

        The Upgrader works meticulously to ensure that the "Dot-Dots" Relative-Path is inserted into the HREF=... Attribute so that each page can properly render a Favicon when it is placed inside the Root Java-Doc Directory.
        Parameters:
        faviconFileFormat - An instance of IF - the Image-Format of the Favicon-File.

      • addHeaderTags

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade addHeaderTags​(java.lang.Iterable<TagNode> headerTags)
        This allows a user to request that HTML-Tags be inserted into Java Doc pages. When HTML TagNode's are provided to this list, all Java Doc HTML Pages will have those tags inserted into their headers.

        IMPORTANT: The tags that are provided will be inserted into every '.html' file inside the root Java Doc directory tree. Furthermore, it is not possible to specify differences for tags as they are inserted into the pages.

        If there are tags that should be inserted into all pages, for example a canonical URL, some general 'keywords', or possibly company, author, contact, or images-links, then providing those tags (as instances of TagNode) here would work great.

        If there are HTML <HEAD>, <META> or <LINK> tags that will differ dependent into which file they are inserted, you will have to manually add them using one of the callback-hooks provided by the upgrader.

        When this field is used, your pages will resemble the page screen-cap in the image below.

        NOTE: There are no default tags - you must choose elements of your own and pass them to this configuration-setting field.

        HTML Header Tags, inserted by Upgrader
        Parameters:
        headerTags - HTML-Tags to be inserted into a page's <HEAD>...</HEAD> Section

      • addHeaderBlock

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade addHeaderBlock​(java.util.Vector<HTMLNode> headerStuff)
        This accepts a full-fledged Vector. This entire Vector will be inserted into the HTML ... section of all Java Doc Pages.
        Parameters:
        headerStuff - HTML-Block to be inserted into a page's <HEAD>...</HEAD> Section

      • runLinksChecker

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade runLinksChecker()
        Requests that all Inter-Page <A HREF=...> Links / URL's be checked. This is a costly operation, and requires more time to complete an Upgrade. This operation, however, can be an invaluable tool if and when user has imported links from <EMBED>-Tag HTML Files.

        Default Setting:
        Note that it is much smarter to leave the LinksChecker off as a default. It's default setting is "turned off."

      • setTabsPolicy

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setTabsPolicy​(int spacesPerTab,
                             boolean relativeOrAbsolute)
        Sets a tab-replacement policy for code-hilited HTML.
        Parameters:
        spacesPerTab - The number of spaces that should be used as a substitue for a tab-character ('\t') when hiliting source-code.
        relativeOrAbsolute - When this parameter receives TRUE, a tab-character is used to symbolize however many spaces are needed to place the cursor at the next rounded-integral number-of-spaces - modulo the value in 'spacesPerTab'.

        If a tab-charcter is found at index 13 in a line-of-code, and the value passed to 'spacesPerTab' were 4, then the number of spaces inserted would be 3. This is because precisely 3 spaces would skip to index 16, which happens to be the next-highest rounded-multiple of 4.

        When this parameter receives FALSE, a tab-character is always replaced by the exact number of space-characters specified by spacesPerTab.
        Throws:
        java.lang.IllegalArgumentException - If a number less than 1 or greater than 20 is passed to parameter 'spacesPerTab'
        See Also:
        StrIndent.setCodeIndent_WithTabsPolicyRelative(String, int, int), StrIndent.setCodeIndent_WithTabsPolicyAbsolute(String, int, String)

      • 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'.

        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)

        Singleton Tags:
        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.

        Dubious HTML Cases:
        JavaDoc generates valid HTML. A programmer who inserts HTML into his Java-Doc Generated Web-Pages will certainly encounter errors where this check helps finding unclosed HTML Problems inside their documentation.

        There are a number of 'Questionable Cases' or 'Boundary Cases' on what actually constitutes Valid-HTML. The <LI>-Tag, for instance. There are some Web-Designers who feel that it is not necessary to close these tags with a '</LI>'.

        However, this checker will not allow this scenario. In order to allow for unclosed, non-singleton tags, this checker must be turned off.
        Parameters:
        checkBalance - The value of this parameter can turn the balance checker on or off.

      • setExtraTasks

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setExtraTasks​
            (java.util.function.Consumer<JavaDocHTMLFile> 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 JavaDocHTMLFile.

        When the Upgrader is provided with an Extra Tasks, the user may use that instance to modify the JavaDoc Web-OPage in any arbitrary way he chooses. A programmer might wish to add some recurring-automated comments to each method description, or perhaps insert an icon or glyph to all of the Classes inside of one his Package's.

        This java.util.function.Consumer<JavaDocHTMLFile> 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.

        Using Torello.HTML:
        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.

        Regardless, just about everything you would need to know about a Java Doc HTML Page is provided in the parameters of the class JavaDocHTMLFile
        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.

        The class JavaDocHTMLFile provides many accessor methods to retrieve the Summary Tables, and the HTML Details - along with reflection-classes about the Method's, Field's, etc... that they describe

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

        Very often, when building the pages package-summary.html for a particular JavaDoc package, the classes and interfaces that are inserted into the page will look horribly skewed - if the comment section of the classes contained any detailed HTML segments. Setting a Package Summary Cleaner will remove most of the text inserted into that page.
        Parameters:
        packageSummaryCleaner - Java Lambda for modifying Vectorized-HTML.

      • setPackageList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setPackageList​
            (java.lang.Iterable<BuildPackage> packageList)
        Often, for the purposes of "development speed" during the development phase of a project, it can be of tremendous benefit to skip, altogether, the Upgrade Process of some of the Packages in a Project.

        Filter Behavior:
        Packages which are explicity named by the input parameter list 'packageList' are INCLUDED not EXCLUDED by the Internal Upgrder Logic.

        Default Setting:
        By default, initiating an upgrade will cause this Package's internal Upgrade Logic to iterate ALL Packages found / present in the 'javadoc/' output directory.

        Input-Parameter Type:
        If Java-HTML Package "Build" is not actually being utilized by your Project's Build-System, there is a nearly identical variant of this method that accept's Package-Names as Java String's, instead of instances of class "BuildPackage".

        (Class BuildPackage is one of the Primary Data-Classes for the Build Tool Torello.Java.Build).
        Parameters:
        packageList - A list of instances of the Build Package's class BuildPackage.
        Returns:
        'this' instance, for method-invocation chaining.
        See Also:
        setPackageList(String[])

      • setPackageList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setPackageList​(java.lang.String... packageList)
        Often, for the purposes of "development speed" during the development phase of a project, it can be of tremendous benefit to skip, altogether, the Upgrade Process of some of the Packages in a Project.

        Filter Behavior:
        Packages which are explicity named by the input parameter list 'packageList' are INCLUDED not EXCLUDED by the Internal Upgrder Logic.

        Default Setting:
        By default, initiating an upgrade will cause this Package's internal Upgrade Logic to iterate ALL Packages found / present in the 'javadoc/' output directory.
        Parameters:
        packageList - A list of Package-Name's as a String.
        Returns:
        'this' instance, for method-invocation chaining.
        See Also:
        setPackageList(Iterable)

      • setGenerateFrames

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setGenerateFrames​(boolean generateFrames)
        A Configuration-Setting for requesting that the Upgrader Auto-Generate the original Java 'package-frame.html' & 'overview-frame.html' Files.

        Back by Popular Demmand:
        By default, the Upgrader actually will recreate the original HTML-<IFRAME> Elements as existed on Java-Doc Web-Pages before and during Java-11 when they were deprecated. These frames were fully removed by Java LTS 17 (for why? I have no idea).

        As an aside, as a "JavaDoc Professional" it is this programmers belief that Java-Doc becomes nearly "unusable" without the frame files, and I truly have little idea why they were elminated.

        Anyway, below is shown the original HTML from the JDK-11 variant of JavaDoc. Some space-indentation has been added to the original HTML, merely to make the contents more readable here on this page.

        HTML Elements:
        <main role="main">

    <div class="mainContainer">

        <div class="leftContainer">

            <div class="leftTop">
                <iframe src="overview-frame.html" name="packageListFrame" title="All Packages"></iframe>
                </div>

            <div class="leftBottom">
                <iframe src="allclasses-frame.html" name="packageFrame" title="All classes and interfaces (except non-static nested types)"></iframe>
                </div>
                </div>

        <div class="rightContainer">
            <iframe src="overview-summary.html" name="classFrame" title="Package, class and interface descriptions" class="rightIframe"></iframe>
            </div>
            </div>
            </main>
        Parameters:
        generateFrames - The boolean-Setting for this Configuration-Field
        Returns:
        'this' instance, for method-invocation chaining.
        Throws:
        UpgradeException - If 'generateFrames' is passed FALSE, but you have earlier configured / applied an 'overview-frame.html' sorter.
        See Also:
        PackageSummaryHTML.JD_FRAMES_WARNING_MESSAGE

      • setOverviewFrameSorter

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public Upgrade setOverviewFrameSorter​(java.lang.String[] sectionNames,
                                      java.lang.String[][] sectionContents)
        Generate and sort an 'overview-frame.html' File.
        Parameters:
        sectionNames - List of "Categories" or "Sections" for the packages
        sectionContents - List of Packages for each Category / Section.
        Returns:
        'this' instance, for method-invocation chaining.