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).
    Sun-Oracle modified (slightly) the HTML generated by the Java-Doc released with Java 14 (LTS) and with Java 17 (LTS). Though the HTML changes are somewhat minor, writing a version-detector class and a version-dispatch HTML generator simply cannot be done until the development and the optimization of all expected features for this tool have been completed. Handing the changes (some HTML <TABLE> elements were changed to <DIV> elements) will not be a lot of work, though worrying about the issues makes no sense until all of the kinks, features, optimizations, improvements & bugs for the Java 11 (LTS) version have been completed.


    Java-Parser Note:
    The features and functions of the other packages in the Java-HTML Jar Distribution Library are not dependent on the Java Doc Upgrader Tool, outside of how their Documentation Pages look! This class was used to generate the documentation you are reading right now. HTML Parsing and other assorted Java Tools are not dependent on anything inside this package.

    The Java Parser Library Distribution JAR Must Be in the CLASSPATH to Run


    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:
        // 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/global-external-html-ids.properties";

    // 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:
        // 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:
         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:
         public static final String FAVICON_FILE_NAME = "favicon";

      • JAVA_SCRIPT_FILE_NAME

        🡅  🡇  ⇈  ⮫ 
        public static final java.lang.String JAVA_SCRIPT_FILE_NAME
        The name of the (very brief) '.js' file.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final String JAVA_SCRIPT_FILE_NAME = "JDU.js";

      • rt

        🡅  🡇  ⇈  ⮫ 
        public static final java.lang.Runtime rt
        Code:
        Exact Field Declaration Expression:
         public /* Made Public With The Big-Move, was Package-Private */
     static final Runtime rt = Runtime.getRuntime();

      • FSEP

        🡅  🡇  ⇈  ⮫ 
        public static final char FSEP
        Code:
        Exact Field Declaration Expression:
         public /* Made Public AND WAS protected */
     static final char FSEP = File.separator.charAt(0);

      • rootJavaDocDirectory

        🡅  🡇  ⇈  ⮫ 
        public final java.lang.String rootJavaDocDirectory
        The Root Java Doc output directory. This is usually just 'javadoc/'
        Code:
        Exact Field Declaration Expression:
         public /* Made Public AND WAS protected */
     // protected
     final String rootJavaDocDirectory;

      • rootSourceFileDirectories

        🡅  🡇  ⇈  ⮫ 
        public final java.lang.String[] rootSourceFileDirectories
        Identical to a a 'CLASSPATH', except the Upgrader will only search for source files. Jar Files are ignored by this Tool.
        Code:
        Exact Field Declaration Expression:
         public /* Made Public AND WAS protected */
     /* protected */ final String[] rootSourceFileDirectories;

      • faviconImageFileName

        🡅  🡇  ⇈  ⮫ 
        public 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:
         public /* Made Public With The Big-Move, was Protected */
     /* 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. By default, this field is set FALSE

        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:
         protected boolean VERBOSE_PRINT_STEPS = false;

      • logFile

        🡅  🡇  ⇈  ⮫ 
        protected java.lang.Appendable logFile
        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 the 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.
        See Also:
        setLogFile(Appendable), setLogFile(String)
        Code:
        Exact Field Declaration Expression:
         protected Appendable logFile = null;

      • projectGlobalEmbedTagsMap

        🡅  🡇  ⇈  ⮫ 
        public final java.util.Map<java.lang.String,​java.lang.String> projectGlobalEmbedTagsMap
        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 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 - 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.

        Global Embed Tags Map File
        See Also:
        setProjectGlobalEmbedTagsMapFile(String), setProjectGlobalEmbedTagsMap(Map)
        Code:
        Exact Field Declaration Expression:
         public
     /* protected */ final Map<String, String> projectGlobalEmbedTagsMap = new HashMap<>();

      • 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:
         protected String jdCSS = null;

      • packageSummaryCleaner

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Consumer<java.util.Vector<HTMLNode>> packageSummaryCleaner
        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. The default cleaner may be viewed in the source-code file:

        CleanPackageSummaries
        See Also:
        setPackageSummaryCleaner(Consumer), useDefaultPackageSummaryCleaner()
        Code:
        Exact Field Declaration Expression:
         protected Consumer<Vector<HTMLNode>> packageSummaryCleaner = null;

      • extraTasks

        🡅  🡇  ⇈  ⮫ 
        public java.util.function.Consumer<JavaDocHTMLFile> 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<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.

        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 JavaDocHTMLFile class.
        See Also:
        setExtraTasks(Consumer)
        Code:
        Exact Field Declaration Expression:
         public /* Made Public With The Big-Move, was Protected */
     /* protected */ Consumer<JavaDocHTMLFile> extraTasks = 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:
         protected boolean checkBalance = true;

      • stats

        🡅  🡇  ⇈  ⮫ 
        public Stats stats
        Keeps some statistics about the upgrade / build. View / use after upgrader completes.
        Code:
        Exact Field Declaration Expression:
         public /* Made Public With The Big-Move, was protected */
     /* protected */ Stats stats = new Stats();

      • headerTags

        🡅  🡇  ⇈  ⮫ 
        protected java.util.Vector<HTMLNode> headerTags
        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
        See Also:
        addHeaderTags(Iterable)
        Code:
        Exact Field Declaration Expression:
         protected Vector<HTMLNode> headerTags = new Vector<>();

      • linksChecker

        🡅  🡇  ⇈  ⮫ 
        protected Torello.JavaDoc.HTMLProcessors.LinksChecker linksChecker
        Instance which checks for broken links in Java Doc Pages.
        See Also:
        runLinksChecker()
        Code:
        Exact Field Declaration Expression:
         protected LinksChecker linksChecker = null;

      • relativeOrAbsolute

        🡅  🡇  ⇈  ⮫ 
        protected java.lang.Boolean relativeOrAbsolute
        Whether a relative or absolute tab-replacement policy is used. When this field is null (which is the default) tab-characters are ignored.
        See Also:
        setTabsPolicy(int, boolean)
        Code:
        Exact Field Declaration Expression:
         protected Boolean relativeOrAbsolute = null;

      • indentor

        🡅  🡇  ⇈  ⮫ 
        public java.util.function.UnaryOperator<java.lang.String> indentor
        Applies the tabs-policy to lines or blocks of source-code.

        WARNING: The default code-indentation policy with throw an exception, and cause the Messager to generate a User-Error if any lines of source-code contain tab-characters ('\t').
        Code:
        Exact Field Declaration Expression:
         public /* Made Public With The Big-Move, was protected */
     /* protected */ UnaryOperator<String> indentor = (String s) -> StrIndent.setCodeIndent(s, 1);

      • 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:
         protected Predicate<String> summaryRemoveFilter = ALWAYS_TRUE;

      • 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:
         protected Predicate<String> hiLiteSourceCodeFileFilter = ALWAYS_TRUE;

      • 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. By default all Method's are automatically hilited.

        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:
         protected Predicate<String> hiLiteAllMethodsFilter = ALWAYS_TRUE;

      • 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. By default all Field's are automatically hilited.

        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:
         protected Predicate<String> hiLiteAllFieldsFilter = ALWAYS_TRUE;

      • 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. By default, Constructor's are NOT automatically hilited.

        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 setHiLiteAllConstructorsFilter(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:
         protected Predicate<String> hiLiteAllConstructorsFilter = ALWAYS_FALSE;

      • hiLiteAllAnnotationElemsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> hiLiteAllAnnotationElemsFilter
        This filter is used to decide which Annotation '.html' Java-Doc Files will have their element-declarations hilited and inserted in their respective JavaDoc '.html' pages. By default all Annotation Element's are automatically hilited.

        NOTE: Only Java Annotations (@interface) files allow these elements to be declared. The vast majority of JavaDoc HTML Pages will not have a details section for Annotation Members / Elements.

        The HiLite Annotation-Elements Filter is loaded into this Predicate<String> by calling:
        StrFilter.strListREJECT_NOIOE(String, boolean)

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

        HiLited Annotation Element Declaration
        See Also:
        setHiLiteAllAnnotationElemsFilter(Predicate), doNotHiLiteAnnotationElems()
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> hiLiteAllAnnotationElemsFilter = ALWAYS_TRUE;

      • hiLiteAllEnumConstantsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> hiLiteAllEnumConstantsFilter
        This filter is used to decided which Enumeration '.html' Java-Doc Files will have their constant-declarations hilited and inserted in their respective JavaDoc '.html' pages. By default, Enum Constants are NOT automatically hilited.

        NOTE: Only Java 'enum' files allow enumeration constants to be declared. The vast majority of JavaDoc HTML Pages will not have a details section for these types of elements.

        ALSO: (Again) These constants are just the ones defined inside of a Java 'enum', and the vast majority of such constants are nothing more than a simple name token, so hiliting them would be largely immaterial. However, in Java, it is allowed to pass parameter information when creating an enumeration, and in such cases, if you would like to show-case the parameter-expressions used to construct an enum's constants, then this procedure could be of use.

        A HiLite Enum-Constants Filter is loaded into this Predicate<String> by calling:

        HiLite All Constants Text File
        StrFilter.strListREJECT_NOIOE(String, boolean)

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

        HiLited Enumerated Constant Declaration
        See Also:
        setHiLiteAllEnumConstantsFilter(Predicate), hiLiteEnumConstants()
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> hiLiteAllEnumConstantsFilter = ALWAYS_FALSE;

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

        The default CSS File may be viewed here:

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

      • validateHTMLFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> validateHTMLFilter
        This filter allows you to turn off HTML Validation for some or all of the class-files in your upgrade process. 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

        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.

        IMPORTANT: If a value of FALSE is assigned to the field checkBalance, then any Predicate that's ultimately assigned here will have no effect on the upgrade process. The boolean-value of 'checkBalance' supersedes the results of this filter-predicate, and when that boolean is false, this Predicate is effectively ignored.

        FINALLY: The results of this Predicate do not affect the validation of externally-linked <EMBED CLASS='external-html'> files. If you would like avoid validating those files, you must set the checkBalance flag to FALSE. All external-html files (imported with the embed-tag) are checked for valid HTML before the upgrade process even starts, in a separate programming module.
        See Also:
        setValidateHTMLFilter(Predicate), doNotValidateHTML()
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> validateHTMLFilter = ALWAYS_TRUE;

      • removeAllDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> removeAllDetailsFilter
        By default this filter-predicate is inactive. It can be used to remvoe all details sections present on a Java Doc page.

        NOTE: 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 filter-predicate.
        See Also:
        setRemoveAllDetailsFilter(Predicate)
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> removeAllDetailsFilter = ALWAYS_FALSE;

      • removeAllMethodDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> removeAllMethodDetailsFilter
        This filter can be used to remove all details inside of a Java Doc Page for Method declarations. By default, this filter is inactive.

        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 'Method Details' for that entity are removed.

        NOTE: The 'Summaries' for a page cannot be automtically removed with any of the provided filter-predicates offered by the upgrader.
        See Also:
        setRemoveAllMethodDetailsFilter(Predicate)
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> removeAllMethodDetailsFilter = ALWAYS_FALSE;

      • removeAllConstructorDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> removeAllConstructorDetailsFilter
        This filter can be used to remove all details inside of a Java Doc Page for Constructor declarations. By default, this filter is inactive.

        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 'Constructor Details' for that entity are removed.

        NOTE: The 'Summaries' for a page cannot be automtically removed with any of the provided filter-predicates offered by the upgrader.
        See Also:
        setRemoveAllConstructorDetailsFilter(Predicate)
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> removeAllConstructorDetailsFilter = ALWAYS_FALSE;

      • removeAllFieldDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> removeAllFieldDetailsFilter
        This filter can be used to remove all details inside of a Java Doc Page for Field declarations. By default, this filter is inactive.

        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 'Field Details' for that entity are removed.

        NOTE: The 'Summaries' for a page cannot be automtically removed with any of the provided filter-predicates offered by the upgrader.
        See Also:
        setRemoveAllFieldDetailsFilter(Predicate)
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> removeAllFieldDetailsFilter = ALWAYS_FALSE;

      • removeAllECDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> removeAllECDetailsFilter
        This filter can be used to remove all details inside of a Java Doc Page for Method declarations. By default, this filter is inactive.

        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 'Enum Constant Details' for that entity are removed.

        NOTE: The 'Summaries' for a page cannot be automtically removed with any of the provided filter-predicates offered by the upgrader.

        IMPORTANT Including extensive detail information for many Enum Constant classes often makes the page look over-done and cluttered. Most of the 'enum' documentation pages in the Java HTML JAR Library have had their detail sections removed for their constants.

        FINALLY: Only Java 'enum' files even allow enumeration constants to be declared. The vast majority of JavaDoc HTML Pages will not have a details section for these types of elements.
        See Also:
        setRemoveAllECDetailsFilter(Predicate)
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> removeAllECDetailsFilter = ALWAYS_FALSE;

      • removeAllAEDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        protected java.util.function.Predicate<java.lang.String> removeAllAEDetailsFilter
        This filter can be used to remove all details inside of a Java Doc Page for Annotation Element declarations. By default, this filter is inactive.

        NOTE: Only Java Annotations (@interface) files allow these elements to be declared. The vast majority of JavaDoc HTML Pages will not have a details section for Annotation Members / Elements.

        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 'Constructor Details' for that entity are removed.

        NOTE: The 'Summaries' for a page cannot be automtically removed with any of the provided filter-predicates offered by the upgrader.
        See Also:
        setRemoveAllAEDetailsFilter(Predicate)
        Code:
        Exact Field Declaration Expression:
         protected Predicate<String> removeAllAEDetailsFilter = ALWAYS_FALSE;

    • 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.
        See Also:
        rootJavaDocDirectory, rootSourceFileDirectories

    • Method Detail

      • testSummaryRemoveFilter

        🡅  🡇  ⇈  ⮫ 
        public boolean testSummaryRemoveFilter​(java.lang.String s)
        Runs the (private) Configuration-Predicate summaryRemoveFilter
        Parameters:
        s - Any Java-String to test against this Predicate.
        Returns:
        This Predicate's results after applying it to parameter 's'.
        See Also:
        summaryRemoveFilter
        Code:
        Exact Method Body:
         return summaryRemoveFilter.test(s);

      • testHiLiteAllFieldsFilter

        🡅  🡇  ⇈  ⮫ 
        public boolean testHiLiteAllFieldsFilter​(java.lang.String s)
        Runs the (private) Configuration-Predicate hiLiteAllFieldsFilter
        Parameters:
        s - Any Java-String to test against this Predicate.
        Returns:
        This Predicate's results after applying it to parameter 's'.
        See Also:
        hiLiteAllFieldsFilter
        Code:
        Exact Method Body:
         return hiLiteAllFieldsFilter.test(s);

      • testCSSTagsFilter

        🡅  🡇  ⇈  ⮫ 
        public boolean testCSSTagsFilter​(java.lang.String s)
        Runs the (private) Configuration-Predicate cssTagsFilter
        Parameters:
        s - Any Java-String to test against this Predicate.
        Returns:
        This Predicate's results after applying it to parameter 's'.
        See Also:
        cssTagsFilter
        Code:
        Exact Method Body:
         return cssTagsFilter.test(s);

      • testValidateHTMLFilter

        🡅  🡇  ⇈  ⮫ 
        public boolean testValidateHTMLFilter​(java.lang.String s)
        Runs the (private) Configuration-Predicate validateHTMLFilter
        Parameters:
        s - Any Java-String to test against this Predicate.
        Returns:
        This Predicate's results after applying it to parameter 's'.
        See Also:
        validateHTMLFilter
        Code:
        Exact Method Body:
         return validateHTMLFilter.test(s);

      • setRemoveAllDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setRemoveAllDetailsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter can be used to remove all 'Detail Sections' on a Java Doc page. Note that what will be left shall include only the information at the top of the page, and the various summaries.
        See Also:
        removeAllDetailsFilter
        Code:
        Exact Method Body:
         this.removeAllDetailsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setRemoveAllMethodDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setRemoveAllMethodDetailsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        Sets the filter-predicate which may be used to remove all 'Method Details' in a Java Doc Page. By default this filter is inactive.
        See Also:
        removeAllMethodDetailsFilter
        Code:
        Exact Method Body:
         this.removeAllMethodDetailsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setRemoveAllConstructorDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setRemoveAllConstructorDetailsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        Sets the filter-predicate which may be used to remove all 'Constructor Details' in a Java Doc Page. By default this filter is inactive.
        See Also:
        removeAllConstructorDetailsFilter
        Code:
        Exact Method Body:
         this.removeAllConstructorDetailsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setRemoveAllFieldDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setRemoveAllFieldDetailsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        Sets the filter-predicate which may be used to remove all 'Field Details' in a Java Doc Page. By default this filter is inactive.
        See Also:
        removeAllFieldDetailsFilter
        Code:
        Exact Method Body:
         this.removeAllFieldDetailsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setRemoveAllECDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setRemoveAllECDetailsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        Sets the filter-predicate which may be used to remove all 'Enum Constant Details' in a Java Doc Page. By default this filter is inactive.

        NOTE: Only 'enum' types will ever have Enum Constant's.
        See Also:
        removeAllECDetailsFilter
        Code:
        Exact Method Body:
         this.removeAllECDetailsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setRemoveAllAEDetailsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setRemoveAllAEDetailsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        Sets the filter-predicate which may be used to remove all 'Element Details' in a Java Doc Page. By default this filter is inactive.

        NOTE: Only Annotations (@interface) will ever have Annotation Element's.
        See Also:
        removeAllAEDetailsFilter
        Code:
        Exact Method Body:
         this.removeAllAEDetailsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • turnOnVerboseProcessPrint

        🡅  🡇  ⇈  ⮫ 
        public Upgrade turnOnVerboseProcessPrint()
        This turns on 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 FALSE.
        See Also:
        VERBOSE_PRINT_STEPS
        Code:
        Exact Method Body:
         VERBOSE_PRINT_STEPS = true;
 Messager.setVerbose(true);
 return this;

      • setLogFile

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setLogFile​(java.lang.Appendable logFile)
        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 the 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 - This may be any instance of Appendable that is capable of receiving log-file writes.
        Returns:
        An instance of 'this' upgrader, for convenience.
        See Also:
        logFile
        Code:
        Exact Method Body:
         this.logFile = logFile;
 Messager.setLogAppendable(logFile);

 return this;

      • setLogFile

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setLogFile​(java.lang.String logFileName)
        Log information will be duplicated 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:
         // This is just used / passed to the "Exception Checker" (below) to build a more
 // readable Exception-Message.

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

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

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

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

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

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

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

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

         return this;
     }
 };

 Messager.setLogAppendable(logFile);

 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:
         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:
         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 all Method's are automatically hilited.

        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:
         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 all Field's are automatically hilited.

        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:
         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, Constructor's are NOT automatically hilited.

        IMPORTANT: By default, constructors are not automatically hilited. You must explicitly request to have the constructors for specific CIET's hilited - using this method.. Alternatively, you may invoke hiLiteConstructors() to have all constructor bodies (for all CIET's) hilited and inserted into Java Doc 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 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:
         this.hiLiteAllConstructorsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setHiLiteAllAnnotationElemsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setHiLiteAllAnnotationElemsFilter​
            (java.util.function.Predicate<? super java.lang.String> annotationNameFilter)
        This filter decides which Java-Doc Web-Pages (for Java Annotations) will have their element-declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default all Annotation Element's are automatically hilited.

        NOTE: Only Java Annotations (@interface) files allow these elements to be declared. The vast majority of JavaDoc HTML Pages will not have a details section for Annotation Members / Elements.

        The filter-parameter ('annotationNameFilter') 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 Annotation whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see the Element Declarations HiLited, and FALSE if the Upgrader should skip hiliting element declarations for the particular annotation.

        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:



        FINALLY: It ought to be obvious that if you attempt to 'pass' a Java Class or Interface that is not actually an instance of '@interface' using this Predicate, such a mistake will be gracefully ignored.

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

        HiLited Annotation Element Declaration
        Parameters:
        annotationNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Java Annotation.
        See Also:
        doNotHiLiteAnnotationElems(), hiLiteAllAnnotationElemsFilter, StrFilter
        Code:
        Exact Method Body:
         this.hiLiteAllAnnotationElemsFilter = RAW_TYPES_FIX(annotationNameFilter);  return this;

      • setHiLiteAllEnumConstantsFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setHiLiteAllEnumConstantsFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        This filter decides which Java-Doc 'enum'Web-Pages will have all their enumeration-constant declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default, Enum Constants are NOT automatically hilited.

        NOTE: Only Java 'enum' files allow enumeration constants to be declared. The vast majority of JavaDoc HTML Pages will not have a details section for these types of elements.

        IMPORTANT: By default, these constants are not automatically hilited. You must explicitly request to have the Enumeration Constants for a specific 'enum' hilited - using this method.. Alternatively, you may invoke hiLiteEnumConstants() to have the all constants declared in any / all enum's hilited and inserted into their respective Java Doc 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 'enum' whose source-code documentation-file is being Code-HiLited.

        The Predicate should return TRUE if you would like to see the Enumeration Constant Declarations HiLited, and FALSE if the Upgrader should skip hiliting constant 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:



        FINALLY: It ought to be obvious that if you attempt to 'pass' a Java Class or Interface that is not actually an instance of 'enum' using this Predicate, such a mistake will be gracefully ignored.

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

        HiLited Enum Constant Declaration
        Parameters:
        cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Java Enum Constant.
        See Also:
        hiLiteEnumConstants(), hiLiteAllEnumConstantsFilter, StrFilter
        Code:
        Exact Method Body:
         this.hiLiteAllEnumConstantsFilter = 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:
         this.cssTagsFilter = RAW_TYPES_FIX(cietNameFilter);  return this;

      • setValidateHTMLFilter

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setValidateHTMLFilter​
            (java.util.function.Predicate<? super java.lang.String> cietNameFilter)
        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.\

        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

        View This Example:

        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()

        MAIN POINT: Because there is a call to the setCheckBalance(false) Configuration Method, the subsequent call to setValidateHTMLFilter is no different than a "No Op", it has no effect on the final processing.
        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:
        doNotValidateHTML(), validateHTMLFilter, StrFilter
        Code:
        Exact Method Body:
         this.validateHTMLFilter = 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:
         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:
         this.hiLiteSourceCodeFileFilter = 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 encounters.

        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:
         this.hiLiteAllConstructorsFilter = ALWAYS_TRUE; return this;

      • hiLiteEnumConstants

        🡅  🡇  ⇈  ⮫ 
        public Upgrade hiLiteEnumConstants()
        Differing from Fields and Methods, enumeration constants in an upgraded Java-Doc 'enum' Page are not automatically hilited. You need to explicity ask the upgrader to hilite Constant Declarations. This method will indicate to the upgrader to hilite the Enumeration Constants for all enum's that it encounters.

        This will set a filter Predicate that returns TRUE for every enum about which it is queryied. If this method is used, then all of the Java-Doc Upgraded 'enum' Pages will have their Enumeration Constant Declaration HiLited.

        NOTE: Again, these constants are just the ones defined inside of a Java 'enum', and the vast majority of such constants are nothing more than a simple name token, so hiliting them would be largely immaterial! However, in Java, it is allowed to pass parameter information when creating an enumeration, and in such cases, if you would like to show-case the parameter-expressions used to construct an enum's constants, then this procedure could be of use.
        See Also:
        hiLiteAllEnumConstantsFilter, setHiLiteAllEnumConstantsFilter(Predicate)
        Code:
        Exact Method Body:
         this.hiLiteAllEnumConstantsFilter = 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:
         this.cssTagsFilter = ALWAYS_FALSE; return this;

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

        Global Embed Tags Map File
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        Throws:
        UpgradeException - If there are problems loading the file
        See Also:
        setProjectGlobalEmbedTagsMap(java.util.Map<java.lang.String, java.lang.String>), projectGlobalEmbedTagsMap
        Code:
        Exact Method Body:
         if (tagIDMapFileName == null) throw new UpgradeException
     ("The parameter 'tagIDMapFileName' (as a String) was passed NULL.");

 File tagIDMapFile = new File(tagIDMapFileName);

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

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

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

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

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

 Messager.setCurrentFileName(tagIDMapFileName, "<EMBED> Tag ID Map Properties File");
 boolean res = RetrieveEmbedTagMapPropFiles.checkMap(tagIDMap, this.checkBalance, "");

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

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

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

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

 return this;

      • setProjectGlobalEmbedTagsMap

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setProjectGlobalEmbedTagsMap​
            (java.util.Map<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.
        Parameters:
        tagIDMap - This should map 'DATA-FILE-ID' to an '.html' File-Name.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        projectGlobalEmbedTagsMap
        Code:
        Exact Method Body:
         if (tagIDMap == null) throw new UpgradeException
     ("The parameter 'tagIDMap' (a java.util.Map<String, String>) was passed NULL.");

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

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

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

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

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

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

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

 // invocation chaining
 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:
         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 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.

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

        Default CSS File
        Returns:
        A CSS File which utilizes the added CSS CSSTags CLASSES. The actual file is read from disk, and returned as a String.
        See Also:
        LFEC.readObjectFromFile_JAR(Class, String, boolean, Class), setCustomJDCSSFile(String), CSSTags, jdCSS
        Code:
        Exact Method Body:
         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(), CSSTags
        Code:
        Exact Method Body:
         this.jdCSS = CSSFileAsAString; return this;

      • retrieveDefaultJDUJSFileFromJAR

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String retrieveDefaultJDUJSFileFromJAR()
        There is an (extremely small / limited) Java-Script '.js' File that is added to the output javadoc/ directory.
        Returns:
        The JavaScript File that is read from disk, and returned as a String.
        See Also:
        LFEC.readObjectFromFile_JAR(Class, String, boolean, Class)
        Code:
        Exact Method Body:
         return LFEC.readObjectFromFile_JAR
     (Torello.Data.DataFileLoader.class, "data22.sdat", true, String.class);

      • 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:
         this.faviconImageFileName = FAVICON_FILE_NAME + '.' + faviconFileFormat.toString();

 String[] tokReplaceArr =
     { "INSERT-IMAGE-TYPE-HERE", "INSERT-URL-STRING-HERE" };

 String[] tokenArr =
     { faviconFileFormat.toString(), "DOTDOTS" + faviconImageFileName };
        
 TagNode favicon = new TagNode(StrReplace.r(Features.favicon, tokReplaceArr, tokenArr));

 this.headerTags.insertElementAt(favicon, FAV_HEADER_TAG_VEC_POS);
 this.headerTags.insertElementAt(NEWLINE, FAV_HEADER_TAG_VEC_POS + 1);

 return this;

      • addHeaderTags

        🡅  🡇  ⇈  ⮫ 
        public Upgrade addHeaderTags​(java.lang.Iterable<TagNode> headerTags)
        This allows a user to request that HTML header tags be inserted into Java Doc pages. Please see the instance-field headerTags for more details.
        Parameters:
        headerTags - This may be any set or collection of HTML tags to be placed into the <HEAD>...</HEAD> section of all Java Doc Pages.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        headerTags, addHeaderBlocks(Vector)
        Code:
        Exact Method Body:
         for (TagNode tn : headerTags)
     { this.headerTags.add(tn); this.headerTags.add(NEWLINE); }

 return this;

      • addHeaderBlocks

        🡅  🡇  ⇈  ⮫ 
        public Upgrade addHeaderBlocks​(java.util.Vector<HTMLNode> headerStuff)
        This accepts a full-fledged Vector<HTMLNode>. This entire Vector will be inserted into the HTML <HEAD>...</HEAD> section of all Java Doc Pages.
        Parameters:
        headerStuff - A block of HTML that needs to be inserted.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        headerTags, addHeaderTags(Iterable)
        Code:
        Exact Method Body:
         this.headerTags.addAll(headerStuff);  return this;

      • runLinksChecker

        🡅  🡇  ⇈  ⮫ 
        public Upgrade runLinksChecker()
        Requests that all <A HREF=...> urls be checked. This is a costly operation, and will require more time to do an upgrade. It is better to configure use of the LinksChecker to be off by default. It's default setting is off.
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        linksChecker
        Code:
        Exact Method Body:
         this.linksChecker = new LinksChecker();  return this;

      • 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:
        relativeOrAbsolute, spacesPerTab, StrIndent.setCodeIndent_WithTabsPolicyRelative(String, int, int), StrIndent.setCodeIndent_WithTabsPolicyAbsolute(String, int, String)
        Code:
        Exact Method Body:
         this.spacesPerTab       = spacesPerTab;
 this.relativeOrAbsolute = relativeOrAbsolute;

 if ((spacesPerTab < 1) || (spacesPerTab > 20)) throw new IllegalArgumentException
     ("A tab-character ('\t') cannot represent less than one or more than twenty " +
     "spaces.  You have passed [" + spacesPerTab + "]");

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

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

 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:
         this.checkBalance = checkBalance; return this;

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

        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.
        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
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        See Also:
        extraTasks
        Code:
        Exact Method Body:
         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 may be viewed in the source-code file:

        CleanPackageSummaries
        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:
         this.packageSummaryCleaner = packageSummaryCleaner;  return this;

      • getPackageCIETList

        🡅  🡇  ⇈  ⮫ 
        public java.util.TreeSet<java.lang.String> getPackageCIETList​
            (java.lang.String packageName)
        Returns the list of Types/CIET's that are defined for a particular package. The list that is returned is comprised out of only the classes & types for which Java Doc has generated a Web-page!
        Parameters:
        packageName - This should be the complete name of the package whose list of defined types / CIET's is being requested.
        Returns:
        This actually returns a 'clone' of the list of defined classes. A clone is used so that if the user mistakenly or accidentally changes this list, it will not affect the internal workings and use of this master list.
        Code:
        Exact Method Body:
         return (TreeSet<String>) getPackageTypesList(packageName).clone();

      • parserInstanceChoice

        🡅  🡇  ⇈  ⮫ 
        public byte parserInstanceChoice()
         public static final byte SUN_ORACLE     = 1;
 public static final byte JAVA_PARSER    = 2;
 public static final byte DIFF_BOTH      = 3;
        Returns:
        The value currently assigned to Parser-Instance Choice
        Code:
        Exact Method Body:
         return parserInstanceChoice;

      • setParserInstanceChoice

        🡅  🡇  ⇈  ⮫ 
        public Upgrade setParserInstanceChoice​(byte choice)
         public static final byte SUN_ORACLE     = 1;
 public static final byte JAVA_PARSER    = 2;
 public static final byte DIFF_BOTH      = 3;


        The default Parser-Instance is the Sun/Oracle Parser offered in JDK Package com.sun.source.tree.*. This Upgrader was initially developed using the Java Parser Library, and that library contains to be maintained in this source code, as it is an invaluable tool for testing and debugging.

        If you so choose to opt for the Java-Parser choice, make sure that the Java-Parser JAR File is in your 'CLASSPATH' environment variable. That JAR File is not included in the Java-HTML JAR.
        Parameters:
        choice - The value to assign to Parser-Instance Choice
        Returns:
        'this' Upgrade instance - for invocation-chaining.
        Code:
        Exact Method Body:
         if ((choice < 1) || (choice > 3)) throw new IllegalArgumentException(
     "You must choose a value of 1, 2 or 3 for Parser-Instance Choice.  You have " +
     "provided [" + choice + "]"
 );

 this.parserInstanceChoice = choice;

 return this;

      • 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 the 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.
        Code:
        Exact Method Body:
         try
 {
     // Returns false if an error occurs, Processes all non-class / non-Type JD HTML Pages
     if (! ExtraFilesProcessor.runAll(this)) return null;

     // Processes Class/Type Pages (Pages for Classes, Interfaces, Enums, Annotations, Recs)
     if (! MainFilesProcessor.runAll(this)) return null;

     // MESSAGER:
     //  1) INVOKES:     println, assertFailGeneralPurpose
     //  2) INVOKED-BY:  Only called once in Upgrade.upgrade, No Where Else
     //  3) RETURNS:     void - NOTHING
     //  4) THROWS:      UpgradeException (assertFailGeneralPurpose)

     stats.saveStatsHTMLFile(this.rootJavaDocDirectory);
 }

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

     return null;
 }

 catch (Throwable t)
 {
     // If a 'throw' made it all the way here, then it is a throw that might be their fault,
     // but it could also be my fault.  Therefore use 'UNEXPECTED_ERROR'

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

     return null;
 }

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

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

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

        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:
         Upgrade upgrader = new Upgrade(argv[0], "");

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

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

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

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

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