java.lang.Object
- Torello.HTML.Tools.JavaDoc.Upgrade

public class Upgrade
extends java.lang.Object

JavaDoc Upgrade (Builder) - Documentation.

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

IMPORTANT NOTE: Before any of the features of this Upgrader Tool will function, an outside JAR-library distribution must be included in the Java CLASSPATH environment variable. The link below is a link to the Java Parser JAR. There is a book available about this library, and an internet Gitter.com Support Page (chat-room) hosted by some of the people involved in writing this JAR library. The complete

Java Parser
Library

has many Java '.jar' files associated, but only the core-library is needed for running the tasks in this Upgrade Tool.

This '.jar' file may be donloaded here:

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

What follows is an example where most 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 results of a call to the standard JDK "javadoc" Tool are sent to this directory 
    public static final String          LOCAL_JAVADOC_DIR               = "javadoc/";

    // This is a simple two-column text-file which links "FILE-ID" to a physical file on
    // the file-system.  The data-columns in this file points the "external-html" files
    // that are automatically inserted into final Java-Doc Web-Browser Documentation Pages.
    // Read more about this in the "Embed Tag" class.  
    public static final String          HILITE_EMBEDID_MAP_FILE         = "Torello/Build/TXT/ids.txt";

    // The location of the web-browser "favicon.jpg" file used in this libraries' documentation pages
    public static final String          FAVICON                         = "Torello/Build/favicon.jpg";

    // The location of the "specialized" CSS definitions file.  The default '.css' file definitions 
    // for the Java-doc Upgrader Tool is left 'un-touched.'  However, a few additional CSS style
    // definitions for some of the specialized classes and methods are added to the original, default file.,
    public static final String          JAVADOC_CSS_FILE                = "Torello/Documentation/JavaDoc.css";

    // This simple text-file lists two or three classes whose public and protected definitions should
    // NOT be hilited and inserted into the documentation HTML web-browser pages.
    public static final String          LEAVEOUT_FIELDS_LIST_FNAME      = "Torello/Build/TXT/SkipAllFields.txt";

    // This simple text-file lists two or three classes whose methods should NOT be hilited and inserted
    // into the documentation web-browser pages.
    public static final String          LEAVEOUT_METHODS_LIST_FNAME     = "Torello/Build/TXT/SkipAllMethods.txt";

    // There currently is one java '.class' file whose source-code is NOT hilited.  All other classes and
    // interfaces included in this Java-HTML jar-library will have had their source-code hilited.  The
    // final hilited file is copied into the web-browser documentation directory, and a link that says
    // "View HiLited Source Code File" is inserted into the HTML page for each and ever class, interface
    // and enumerated type in the jar-library.
    public static final String          LEAVEOUT_SRCFILES_LIST_FNAME    = "Torello/Build/TXT/SkipSrcFile.txt";

    // By default Java has some form of "AI" in it's JavaDoc Tool that "peels out" the first sentence in
    // a method or field declarations comment section.  For any but the most trivial method or field
    // explanation - this one sentence summary is an abysmal failure, and by default, the summary sentences
    // that used to be included in the "Summary" Sections of a JavaDoc web-browser page are eliminated, and
    // only the field or method name, return types, exception-throws and parameter names/types are left.
    //
    // This "text-file" tells the Upgrader to NOT REMOVE the summary description section for two or three
    // classes in the Java-HTML jar-library distribution.  View the Torello.Java.StrIndexOf class, for example 
    // to see what a class "Summary Section" looks like when its "Summary Sentences" are NOT removed.
    public static final String          SKIP_REM_SUMM_LIST_FNAME        = "Torello/Build/TXT/KeepSummaryDesc.txt";

    // This line "converts" the Text-File containing lists of classes, interfaces or enumerated-type names
    // into a simple Predicate<String>... StrFilter inherits "Predicate<String>" and adds several standardized
    // factory-builder methods.
    public static final StrFilter       HILITE_ALL_FIELDS_PRED          = StrFilter.strListREJECT_NOIOE(LEAVEOUT_FIELDS_LIST_FNAME, false);

    // Converts the text-file containing the classes, interfaces or enumerated-type names whose methods
    // should NOT be hilited into a simple Predicate<String> that the upgrader Tool can use.
    public static final StrFilter       HILITE_ALL_METHODS_PRED         = StrFilter.strListREJECT_NOIOE(LEAVEOUT_METHODS_LIST_FNAME, false);

    // Does the same for the text-file regarding "Source Code HiLiting" web-page links.
    public static final StrFilter       HILITE_SRC_FILE_PRED            = StrFilter.strListREJECT_NOIOE(LEAVEOUT_SRCFILES_LIST_FNAME, false);

    // Does the same for the text-file regarding the "Summary Sentences A.I." description part.
    public static final StrFilter       REMOVE_SUMM_PRED                = StrFilter.strListREJECT_NOIOE(SKIP_REM_SUMM_LIST_FNAME, false);

The above static final java.lang.String 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:

    // 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.
    // To use the "Cache System" for the code-hiliter, simply create an empty directory named
    // "cache/" in your root file-system (or some other directory, but be sure to specify the
    // correct file-name).

    String HILITEME_CACHE = "cache/";
    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);

    // Run the Upgrade Tool after making sure to initialize these customizations.
    // NOTE: For the vast majority of documentation projects, none of these "customizations"
    // will seem very important except the: log-file, hiliter-cache, and embed-id map-file.
    new Upgrade                             (LOCAL_JAVADOC_DIR, "")
        .setLogFile                         ("log.html")
        .setEmbedTagsMapFile                (HILITE_EMBEDID_MAP_FILE)
        .setSummaryRemoveFilter             (REMOVE_SUMM_PRED)
        .setHiLiteAllMethodsFilter          (HILITE_ALL_METHODS_PRED)
        .setHiLiteAllFieldsFilter           (HILITE_ALL_FIELDS_PRED)
        .setHiLiteSourceCodeFileFilter      (HILITE_SRC_FILE_PRED)
        .useHiLiteServerCache               (CACHE)
        .setCustomJDCSSFile                 (LFEC.loadFile(JAVADOC_CSS_FILE))
        .useDefaultPackageSummaryCleaner    ()
        .setAdditionalTasks                 (AT::accept)
        .run();

Hi-Lited Source-Code:

View Here: Torello/HTML/Tools/JavaDoc/Upgrade.java
Open New Browser-Tab: Torello/HTML/Tools/JavaDoc/Upgrade.java

Field Summary

Fields
Modifier and Type	Field
`protected AdditionalTasks`	`at`
`protected Predicate<String>`	`cssTagsFilter`
`protected Hashtable<String, String>`	`embedTagIDTable`
`static String`	`FAVICON_FILE_NAME`
`protected String`	`faviconImageFileName`
`protected Predicate<String>`	`hiLiteAllFieldsFilter`
`protected Predicate<String>`	`hiLiteAllMethodsFilter`
`protected HiLiter`	`hiLiter`
`protected Predicate<String>`	`hiLiteSourceCodeFileFilter`
`static String`	`JAVA_DOC_CSS_FILE_NAME`
`protected String`	`jdCSS`
`protected Consumer<String>`	`logFile`
`protected Consumer<Vector<HTMLNode>>`	`packageSummaryCleaner`
`protected RearrangePkgFrame.PackageItems`	`rearrangeFrames`
`protected String`	`rootJavaDocDirectory`
`protected String`	`rootSourceFileDirectory`
`protected Predicate<String>`	`summaryRemoveFilter`
`protected boolean`	`VERBOSE_PRINT_STEPS`

Constructor Summary

Constructors
Constructor

Upgrade(String rootJavaDocDirectory, String rootSourceFileDirectory)

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method
`Upgrade`	`doNotAddCSSTags()`
`Upgrade`	`doNotAddFavicon()`
`Upgrade`	`doNotHiLiteFields()`
`Upgrade`	`doNotHiLiteMethods()`
`Upgrade`	`doNotHiLiteSourceCodeFiles()`
`Upgrade`	`doNotRemoveSummaries()`
`static void`	`main(String[] argv)`
`static String`	`retrieveDefaultJDCSSFileFromJAR()`
`void`	`run(String jdFileName, StorageWriter sw)`
`Upgrade`	`setAdditionalTasks(AdditionalTasks at)`
`Upgrade`	`setCSSTagsFilter(Predicate<? super String> cietNameFilter)`
`Upgrade`	`setCustomJDCSSFile(String CSSFileAsAString)`
`Upgrade`	`setEmbedTagsMap(Map<String,String> tagIDMap)`
`Upgrade`	`setEmbedTagsMapFile(String tagIDMapFileName)`
`Upgrade`	`setHiLiteAllFieldsFilter(Predicate<? super String> cietNameFilter)`
`Upgrade`	`setHiLiteAllMethodsFilter(Predicate<? super String> cietNameFilter)`
`Upgrade`	`setHiLiter(HiLiter hiLiter)`
`Upgrade`	`setHiLiteSourceCodeFileFilter(Predicate<? super String> cietNameFilter)`
`Upgrade`	`setLogFile(String logFileName)`
`Upgrade`	`setLogFile(Consumer<String> consumerLogFile)`
`Upgrade`	`setPackageFrames(String[] packages, String[][] sectionNames, String[][][] sectionContents)`
`Upgrade`	`setPackageSummaryCleaner(Consumer<Vector<HTMLNode>> packageSummaryCleaner)`
`Upgrade`	`setSummaryRemoveFilter(Predicate<? super String> cietNameFilter)`
`Upgrade`	`turnOffVerboseProcessPrint()`
`void`	`upgrade(StorageWriter sw)`
`Upgrade`	`useDefaultPackageSummaryCleaner()`
`Upgrade`	`useHiLiteServerCache(HiLiteMe.Cache cache)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- JAVA_DOC_CSS_FILE_NAME
```
public static final java.lang.String JAVA_DOC_CSS_FILE_NAME
```
  The name of the JavaDoc CSS Definitions file. This filename may not be changed.
  See Also:
  
  Constant Field Values
  
  Code:
  Exact Field Declaration Expression:
  1
  public static final String JAVA_DOC_CSS_FILE_NAME = "JavaDoc.css";
- FAVICON_FILE_NAME
```
public static final java.lang.String FAVICON_FILE_NAME
```
  The name of the favicon-file. This filename and file-format may not be changed.
  See Also:
  
  Constant Field Values
  
  Code:
  Exact Field Declaration Expression:
  1
  public static final String FAVICON_FILE_NAME = "favicon.jpg";
- rootJavaDocDirectory
```
protected final java.lang.String rootJavaDocDirectory
```
  The Root Java Doc output directory. This is usually just 'javadoc/'
  Code:
  Exact Field Declaration Expression:
  1
  protected final String rootJavaDocDirectory;
- rootSourceFileDirectory
```
protected final java.lang.String rootSourceFileDirectory
```
  The Root Source-Code directory
  Code:
  Exact Field Declaration Expression:
  1
  protected final String rootSourceFileDirectory;
- faviconImageFileName
```
protected java.lang.String faviconImageFileName
```
  This can allow a favicon to be added to the 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 a browser like "Google Chrome" or Miscrosoft's "Internet Explorer."
  
  By default, this is set to "favicon.jpg". Unless a request is made to not to, 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. The image-file itself must be stored in the root javadoc directory.
  
  ALSO: To maintain simplicity of the tool, the favicon file-name "favicon.jpg" cannot be changed, nor can the file format of the file be changed. Specifically, the file must be in 'JPEG' image-file format, and it must be named 'favicon.jpg'.
  
  FINALLY: When a 'favicon.jpg' link is inserted into the documentation, the actual image file must manually be copied into the java-doc root directory - or the Upgrader Tool will not point your browser to your favicon's correct location on the file system. After running the Java-Doc on your '.java' source-files, simply copy the 'favicon.jpg' image file to the root output Java Doc directory, and the browser will be able to find the image, using the '<LINK>' element's HREF attribute.
  See Also:
  
  Features.insertFavicon(Vector, String), doNotAddFavicon()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected String faviconImageFileName = FAVICON_FILE_NAME;
- VERBOSE_PRINT_STEPS
```
protected boolean VERBOSE_PRINT_STEPS
```
  The steps that the Java-Doc Upgrader Tools is taking are printed to the provided StorageWriter when this field is set to 'TRUE'.
  
  NOTE: If no instance of StorageWriter is passed to the Upgrader's primary 'run(...)' method, then process-step output will not be displayed - regardless of the value of this 'boolean' field.
  Code:
  Exact Field Declaration Expression:
  1
  protected boolean VERBOSE_PRINT_STEPS = true;
- logFile
```
protected java.util.function.Consumer<java.lang.String> logFile
```
  Output log information is only sent to the passed instance ofStorageWriter, but if a logFile (or any String-Consumer) is provided, this information can be check-pointed to the file-system to prevent large Java StringBuilder instances with hundreds or thousands of log-file String's from slowing down the memory-model or garbage collector.
  See Also:
  
  setLogFile(java.util.function.Consumer<java.lang.String>), setLogFile(java.lang.String)
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Consumer<String> logFile = null;
- embedTagIDTable
```
protected final java.util.Hashtable<java.lang.String,java.lang.String> embedTagIDTable
```
  This stores the a map of TagID fields to their respective HTML-File File-Names on the file-system. It is used in combination with JavaDoc Source-Code HTML Tags that request "External-HTML" be inserted into a JavaDoc HTML Web-Page.
  
  This Upgrader feature allows programmers to write more detailed code documentation (comments) for their Java Classes while reducing the 'clutter' in the code. If a particular method or field needs a lot of commenting, simply type up an external '.html' file (leave off the HTML <HEADER>, <BODY> tags) Then, in your 'java' Source-Code File, insert an HTML <EMBED> tag - and the Upgrader will automatically insert all of the HTML in the external-documentation file you have created.
  
  The 'EMBED' tag needs to look like:
  
  <EMBED CLASS="external-html" DATA-FILE-ID="SOME_ID">
  
  You have the ability to insert these tags into the comments of your source-files, because this Upgrader will replace those HTML elements with the HTML found in the file named by this map. See the image below as an example: Notice that all that has to be provided to the tag is a 'DATA-FIILE-ID' attribute. This 'ID' is mapped to a file-system text-file using this map.
  
  The 'embedTagIDTable' is a really simple 'Map' that translates an '<EMBED>' element's DATA-FILE-ID to an '.html' file-name (that you have written) on the file-system. The Embed Tags Map File used by this Library's Build Script may be viewed below, as an example. This is an exhaustive list of all Externally-Linked HTML Pages for the Java HTML library.
  
  Embed Tags Map File
  See Also:
  
  setEmbedTagsMapFile(String), setEmbedTagsMap(Map)
  
  Code:
  Exact Field Declaration Expression:
  1
  protected final Hashtable<String, String> embedTagIDTable = new Hashtable<>();
- hiLiter
```
protected HiLiter hiLiter
```
  The Code HiLiter instance. The default HiLiter is used, unless setHiLiter is called.
  See Also:
  
  useHiLiteServerCache(HiLiteMe.Cache), setHiLiter(HiLiter)
  
  Code:
  Exact Field Declaration Expression:
  1
  protected HiLiter hiLiter = HiLiter.getDefault(null, "vim", "native");
- jdCSS
```
protected java.lang.String jdCSS
```
  This should be the contents of the intended CSS Rules written to the file 'JavaDoc.css' which shall live in the root-directory of the javadoc file-tree. A link to this CSS file is inserted into each and every java-doc page that is updated.
  
  NOTE: This CSS File is only useable if the user has not invoked doNotAddCSSTags(). If the Upgrader is prohibited from adding CSS Tags to Java-Doc generated web-pages, then the CSS Rules will be not be useable by the browser.
  
  NOTE: The default CSS Rules for the CSS CLASS and ID tags created will be the same ones that are used in this documentation page that you are looking at right now. The default CSS may be changed by assigning a specialized CSS page using the 'setCustomJDCSSFile(String)' method in this class.
  
  The default CSS File may be viewed here:
  
  Default CSS File
  See Also:
  
  setCustomJDCSSFile(String), doNotAddCSSTags()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected String jdCSS = null;
- 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 is:
  
  CleanPackageSummaries.defaultCleaner(Vector)
  See Also:
  
  setPackageSummaryCleaner(Consumer), useDefaultPackageSummaryCleaner(), CleanPackageSummaries.defaultCleaner(java.util.Vector<Torello.HTML.HTMLNode>)
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Consumer<Vector<HTMLNode>> packageSummaryCleaner = null;
- at
```
protected AdditionalTasks at
```
  This is the instance of Additional Tasks registered by the user. To see exactly what parameters are provided to users with AdditionalTasks, please click the link to view the class. An lambda or method of for this Functional Interface allows a programmer to whatever additional changes he would like to make to Java Doc HTML Pages besides the changes automatically made by this Upgrader.
  
  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 an AdditionalTasks function pointer lambda.
  See Also:
  
  setAdditionalTasks(AdditionalTasks)
  
  Code:
  Exact Field Declaration Expression:
  1
  protected AdditionalTasks at = null;
- rearrangeFrames
```
protected RearrangePkgFrame.PackageItems rearrangeFrames
```
  This field may be set if you would like to create upgraded Package Frames. It is not important to know how the RearrangePkgFrameclass works, but click the link to this internally-used class to read about it.
  
  The purpose of this is to allow the user to easily change the layout of the 'package-frame.html' page in Java Doc. Later versions of the Java Doc Tool give warning messages that 'Frames' are going to be deprecated. I personally don't really understand why because they add tremendously to the look-and-feel of the page.
  
  Below is a link to example input arrays, and how they should look. The arrays in the link are actually the exact onese used to rearrange the package-frame.html files employed by this Java HTML library.
  
  Torello.Build.Helper.PackageItems.java
  
  The changes that can be made are explained more clearly with a simple picture:
  See Also:
  
  setPackageFrames(String[], String[][], String[][][])
  
  Code:
  Exact Field Declaration Expression:
  1
  protected RearrangePkgFrame.PackageItems rearrangeFrames = null;
- 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:
  See Also:
  
  setSummaryRemoveFilter(Predicate), doNotRemoveSummaries()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Predicate<String> summaryRemoveFilter = null;
- hiLiteSourceCodeFileFilter
```
protected java.util.function.Predicate<java.lang.String> hiLiteSourceCodeFileFilter
```
  This filter is used to decide which Class, Interface or Enumerated-Type '.java' Source-Code Files will be hilited, and have links to an '.html' file included in their respective Java-Doc '.html' page. The default initialization value of 'null' will result in *all* Java-Doc Pages having a code-hilited HTML Anchor '<A HREF=...>' link inserted into their respective Java-Doc pages. This anchor will link the page to a HiLited-version of the Source-Code '.java' file from which the Java-Doc HTML Page was generated.
  
  The Do Not HiLite Source-Code Files Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which no 'Source Code' File HiLiting is performed. If you view the Documentation Pages for the classes listed in this file, you will see the automatically-added "Source Code" links are actually manually added by a different portion of the build script.
  
  The content of this file are loaded into a StrFilter, and passed to setHiLiteSourceCodeFileFilter(Predicate)
  
  Skip All Source-File HiLiting Text File
  
  The above file is loaded 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:
  See Also:
  
  setHiLiteSourceCodeFileFilter(Predicate), doNotHiLiteSourceCodeFiles()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Predicate<String> hiLiteSourceCodeFileFilter = null;
- hiLiteAllMethodsFilter
```
protected java.util.function.Predicate<java.lang.String> hiLiteAllMethodsFilter
```
  This filter is used to decide which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have their method bodies hilited and inserted in their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *all* Java-Doc Pages having code-hilited method-bodies inserted into their Java-Doc Pages.
  
  The Do Not HiLite Methods Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which no 'Method Body' HiLiting is performed. The file is loaded into a StrFilter, and passed to setHiLiteAllMethodsFilter(Predicate)
  
  Skip All Methods HiLiting Text File
  
  The above file is loaded 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:
  See Also:
  
  setHiLiteAllMethodsFilter(Predicate), doNotHiLiteMethods()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Predicate<String> hiLiteAllMethodsFilter = null;
- hiLiteAllFieldsFilter
```
protected java.util.function.Predicate<java.lang.String> hiLiteAllFieldsFilter
```
  This filter is used to decided which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have their field declarations hilited and inserted in their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *all* Java-Doc Pages having code-hilited field-declarations inserted into their Java-Doc Pages.
  
  The Do Not HiLite Fields Filter for this Jar Distribution Package can be viewed here, below (as an example). The Classes listed in this file are all the classes for which no 'Field Declaration' HiLiting is performed. The file is loaded into a StrFilter, and passed to setHiLiteAllFieldsFilter(Predicate)
  
  Skip All Fields HiLiting Text File
  
  The above file is loaded 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:
  See Also:
  
  setHiLiteAllFieldsFilter(Predicate), doNotHiLiteFields()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Predicate<String> hiLiteAllFieldsFilter = null;
- cssTagsFilter
```
protected java.util.function.Predicate<java.lang.String> cssTagsFilter
```
  This filter is used to decided which Class, Interface or Enumerated-Type '.html' Java-Doc Files will have CSS-Tags inserted into their respective JavaDoc '.html' pages. The default initialization value of 'null' will result in *all* Java-Doc Pages having CSS-Tags inserted into the HTML Elements in their respective JavaDoc Pages.
  
  The Insert CSS Tags procedure is the one which creates CSS CLASS attributes in your Java Doc Pages that look:
  
  To see the complete list of CSS CLASS attributes that are added to a Java Doc '.html' File, please review class Colorize.
  
  The default CSS File may be viewed here:
  
  Default CSS File
  See Also:
  
  setCSSTagsFilter(Predicate), doNotAddCSSTags()
  
  Code:
  Exact Field Declaration Expression:
  1
  protected Predicate<String> cssTagsFilter = null;

Constructor Detail
- Upgrade
```
public Upgrade(java.lang.String rootJavaDocDirectory,
               java.lang.String rootSourceFileDirectory)
```
  This returns a new instance of this class. It will have all empty and null settings, except the root-directory descriptors. It must be initialized with the various builder methods.
  
  This constructor must tell the Upgrader (Builder) which directory contains '.java' Source-Files, and which directory shall contain Java-Doc Generated HTML Documentation Pages.
  
  Parameters:
  
  rootJavaDocDirectory - This is the output directory that was used for the last call to the JavaDoc Utility. The Upgrade Logic should expect to find all class, interface and enumerated types to be hilited in this directory. This parameter may not be null.
  
  rootSourceFileDirectory - This is the location where the '.java' source files for the classes, interfaces and enumerated types named by your list files. This parameter may not be null.
  
  Throws:
  
  UpgradeException - This exception will throw if either of these directories cannot be found, or may not be accessed. The 'getCause()' method of the exception will provide more details of the specific error that occurred.
  
  See Also:
  
  rootJavaDocDirectory, rootSourceFileDirectory

Method Detail

turnOffVerboseProcessPrint
```
public Upgrade turnOffVerboseProcessPrint()
```
This turns off the "verbose" process-step printing information to the log 'StorageWriter' output. This usually helps follow along with Java-Doc Upgrader steps. By default, this field is set to 'TRUE.'
See Also:

VERBOSE_PRINT_STEPS

Code:
Exact Method Body:
1
VERBOSE_PRINT_STEPS = false; return this;

setLogFile
```
public Upgrade setLogFile
            (java.util.function.Consumer<java.lang.String> consumerLogFile)
```
Log information may be sent anywhere. If you need to save Log information somewhere other than a file on the file-system, pass a Java Lambda that accepts Log File String's
Parameters:

consumerLogFile - This may be any lambda which receives log-file writes.

Returns:

An instance of 'this' upgrader, for convenience.

See Also:

logFile

Code:
Exact Method Body:
1
this.logFile = consumerLogFile; return this;

setLogFile

public Upgrade setLogFile(java.lang.String logFileName)

Log information will be sent to the file-name provided, here. This must be an accessible file on the file-system.

Parameters:

logFileName - This may be any file that is accessible on the (UNIX/DOS) filesystem.

Returns:

An instance of 'this' upgrader, for convenience.

Throws:

UpgradeException - When invoked, this method will attempt to write some preliminary header information to the log-file. If this write fails, an UpgradeException will be thrown.

Code:

Exact Method Body:

 String dateTimeStr = StringParse.dateStr('-') + " " + StringParse.timeStr(':');

 String fileHeader = 
     "<HTML>\n<HEAD>\n" +
     "<TITLE>Log " + dateTimeStr + "</TITLE>\n" +
     "<STYLE type='text/css'>\n" + Shell.C.getCSSDefinitions() + "\n</STYLE>\n" +
     "</HEAD>\n" +
     "<BODY STYLE='margin: 1em; background: black; color: white;'>\n\n" +
     "<H1>JavaDoc Upgrader Log</H1>\n" +
     "<CODE>" + dateTimeStr + "</CODE>\n" +
     "<PRE>\n\n";

 // This is just used / passed to the "Exception Checker" (below) to build a more
 // readable Exception-Message.
 final String fileDescription = "Disk / File-System Upgrader Log-Dump File";

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

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

 return this;

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

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

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

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

Cleaned Summaries look as in the picture below:
Parameters:

cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

See Also:

summaryRemoveFilter, doNotRemoveSummaries(), StrFilter

Code:
Exact Method Body:
1
this.summaryRemoveFilter = RAW_TYPES_FIX(cietNameFilter); return this;

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

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

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

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

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

cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

See Also:

doNotHiLiteSourceCodeFiles(), hiLiteSourceCodeFileFilter, StrFilter

Code:
Exact Method Body:
1
this.hiLiteSourceCodeFileFilter = RAW_TYPES_FIX(cietNameFilter); return this;

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

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

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

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

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

cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

See Also:

doNotHiLiteMethods(), hiLiteAllMethodsFilter, StrFilter

Code:
Exact Method Body:
1
this.hiLiteAllMethodsFilter = RAW_TYPES_FIX(cietNameFilter); return this;

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

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

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

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

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

cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

See Also:

doNotHiLiteFields(), hiLiteAllFieldsFilter, StrFilter

Code:
Exact Method Body:
1
this.hiLiteAllFieldsFilter = RAW_TYPES_FIX(cietNameFilter); return this;

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:

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 StrFilter.strListKEEP or StrFilter.strListREJECT

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

Default CSS File
Parameters:

cietNameFilter - The file-name filter. This java.lang.Predicate<String> needs to accept or reject the fully qualified name of a Class, Interface, or Enum.

See Also:

doNotAddCSSTags(), cssTagsFilter, StrFilter

Code:
Exact Method Body:
1
this.cssTagsFilter = RAW_TYPES_FIX(cietNameFilter); return this;

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

Note that the original Java Doc Tool, itself, doesn't always provide the cleanest of pages when the Comments for a Method or Field become very long or intricate. Usually, if HTML of any kind is used in the comments section of a method or field is used, then the Method Summaries or Field Summaries may look awfully skewed.
See Also:

summaryRemoveFilter, setSummaryRemoveFilter(Predicate)

Code:
Exact Method Body:
1
this.summaryRemoveFilter = ALWAYS_FALSE; return this;

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

hiLiteSourceCodeFileFilter, setHiLiteSourceCodeFileFilter(Predicate)

Code:
Exact Method Body:
1
this.hiLiteSourceCodeFileFilter = ALWAYS_FALSE; return this;

doNotHiLiteMethods
```
public Upgrade doNotHiLiteMethods()
```
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 Method Bodies HiLited.
See Also:

hiLiteAllMethodsFilter, setHiLiteAllMethodsFilter(Predicate)

Code:
Exact Method Body:
1
this.hiLiteAllMethodsFilter = ALWAYS_FALSE; return this;

doNotHiLiteFields
```
public Upgrade doNotHiLiteFields()
```
This will set a filter Predicate that returns FALSE for every Class, Interface or Enum. If this method is used, then none of the Java-Doc Upgraded Pages will have their Field Declarations HiLited.
See Also:

hiLiteAllFieldsFilter, setHiLiteAllFieldsFilter(Predicate)

Code:
Exact Method Body:
1
this.hiLiteAllFieldsFilter = ALWAYS_FALSE; return this;

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

This will make it impossible to employ any of the CSS Colorizing or Font-Changing features made available by this Upgrader.
See Also:

cssTagsFilter, setCSSTagsFilter(Predicate)

Code:
Exact Method Body:
1
this.cssTagsFilter = ALWAYS_FALSE; return this;

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

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

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

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

Embed Tags Map File

Returns:

'this' Upgrade instance - for invocation-chaining.

Throws:

UpgradeException - This shall throw any of these files named by the Map are unavailable, not found, or unreadable - or if the map-file itself is unreadable.

IMPORTANT: This method will check each and every external HTML file named by the map to ensure that it exists, and is ready for reading before exiting this method. If any of these files (named by the Map-File} are not accessible, or cannot be found, an UpgradeException will throw.

See Also:

UpgradeException.checkFileExistsAndCanAccess(String, String), HELPER.readMapFile(String), setEmbedTagsMap(java.util.Map<java.lang.String, java.lang.String>), embedTagIDTable

Code:
Exact Method Body:
1 2
Hashtable<String, String> ret = HELPER.readMapFile(tagIDMapFileName); return setEmbedTagsMap(ret);

setEmbedTagsMap

public Upgrade setEmbedTagsMap
            (java.util.Map<java.lang.String,java.lang.String> tagIDMap)

Sets an Embed Tag ID Table using a Java java.util.Map<tring, String>. The first Generic String-Parameter of the map is for a 'DATA-FILE-ID', and the second is expected to hold '.html' file-names.

Parameters:

tagIDMap - This should map 'DATA-FILE-ID' to an '.html' File-Name.

Returns:

'this' Upgrade instance - for invocation-chaining.

Throws:

UpgradeException - This shall throw any of these files named by the Map are unavailable, not found, or unreadable - or if the map-file itself is unreadable.

IMPORTANT: This method will check each and every external HTML file named by the map to ensure that it exists, and is ready for reading before exiting this method. If any of these files (named by the Map-File} are not accessible, or cannot be found, an UpgradeException will throw.

Code:

Exact Method Body:

 embedTagIDTable.clear();

 tagIDMap.forEach((String embedTagID, String htmlFileName) ->
 {
     UpgradeException.checkFileExistsAndCanAccess
         (htmlFileName, "External '.html' file to be inserted");
     embedTagIDTable.put(embedTagID, htmlFileName);
 });

 return this;

useHiLiteServerCache

public Upgrade useHiLiteServerCache(HiLiteMe.Cache cache)

Convenience Method. Invokes setHiLiter(HiLiter) and HiLiter.getDefault(HiLiteMe.Cache, String, String)

Code:

Exact Method Body:

1	setHiLiter(HiLiter.getDefault(cache, "vim", "native")); return this;

setHiLiter
```
public Upgrade setHiLiter(HiLiter hiLiter)
```
Tells this Upgrader to use a particular 'HiLiter'. The default HiLiter is used if this method isn't invoked. Replacement HiLiter's are better explained by the HiLiter Functional-Interface
Parameters:

hiLiter - This should be any implementation of the 'HiLiter'.

Returns:

'this' Upgrade instance - for invocation-chaining.

See Also:

hiLiter

Code:
Exact Method Body:
1
this.hiLiter = hiLiter; return this;

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

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

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

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

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

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

Default CSS File
Returns:

A CSS File which utilizes the added CSS Colorize CLASSES. The actual file is read from disk, and returned as a String.

See Also:

LFEC.readObjectFromFile_JAR(Class, String, boolean, Class), setCustomJDCSSFile(String), Colorize, jdCSS

Code:
Exact Method Body:
1 2
return LFEC.readObjectFromFile_JAR (Torello.Data.DataFileLoader.class, "data14.sdat", true, String.class);

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

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

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

AGAIN: The parameter to this method expects the CSS File to be loaded into a String, this method is not requesting a file-name!
Parameters:

CSSFileAsAString - This parameter can be used to associate a custom CSS definition file with the javadoc output that is generated. The entire contents of the CSS File as a java.lang.String - must be passed as input to this method.

Returns:

'this' Upgrade instance - for invocation-chaining.

See Also:

jdCSS, retrieveDefaultJDCSSFileFromJAR(), Colorize

Code:
Exact Method Body:
1
this.jdCSS = CSSFileAsAString; return this;

doNotAddFavicon
```
public Upgrade doNotAddFavicon()
```
Instructs the Upgrade Tool to avoid adding an HTML Relative Link element with a favicon. The resulting Java-Doc Upgraded Web-Pages will not have favicon images when viewed in a web-browser.

NOTE: It is not possible to "alter" the name or location of the favicon. It must be a '.jpg' file, and it must reside in the Java-Doc Root Directory.
Returns:

'this' Upgrade instance - for invocation-chaining.

See Also:

faviconImageFileName, Features.insertFavicon(Vector, String)

Code:
Exact Method Body:
1
this.faviconImageFileName = null; return this;

setAdditionalTasks
```
public Upgrade setAdditionalTasks(AdditionalTasks at)
```
This allows a user to do his own, user-specified tasks to a java-doc vectorized-html page before it is written to disk. 'AdditionalTasks' is a Java 'Functional Interface"' that can be created by either implementing the interface or using a Lambda Expression

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

PARAMETERS TO FUNCTION POINTER:
- Vector<HTMLNode> html
  The vectorized-HTML JavaDoc Documentation Page
- String jdFileName
  The name of the Java-Doc file that is represented by this vectorized-HTML.
- String srcCodeFileName
  The name of the Source-Code file from which this Java-Doc HTML was originally generated
- String cietFullName
  The full "Class, Interface or Enumerated-Type" with Java-Package Information
- JavaSourceCodeFile jscf
  A parse of the Source-Code file that was generated by the "JavaParser Bridge" Classes
- JavaDocHTMLFile jdhf
  A parse of the Java-Doc file that was generated by this Upgrade Tool.
- StorageWriter sw The log being used to print. This may be used to print messages about the processing to the terminal or log.
Parameters:

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

Returns:

'this' Upgrade instance - for invocation-chaining.

See Also:

at

Code:
Exact Method Body:
1
this.at = at; return this;

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

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

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

CleanPackageSummaries.defaultCleaner(Vector)
Parameters:

packageSummaryCleaner - This should be any lambda or method that will clean the CIET HTML descriptions so they aren't skewed.

Returns:

'this' Upgrade instance - for invocation-chaining.

See Also:

packageSummaryCleaner

Code:
Exact Method Body:
1
this.packageSummaryCleaner = packageSummaryCleaner; return this;

useDefaultPackageSummaryCleaner
```
public Upgrade useDefaultPackageSummaryCleaner()
```
The default Package Description Summary Page Cleaner.
Returns:

'this' Upgrade instance - for invocation-chaining.

See Also:

CleanPackageSummaries.defaultCleaner(java.util.Vector<Torello.HTML.HTMLNode>), packageSummaryCleaner

Code:
Exact Method Body:
1
this.packageSummaryCleaner = CleanPackageSummaries::defaultCleaner; return this;

setPackageFrames
```
public Upgrade setPackageFrames(java.lang.String[] packages,
                                java.lang.String[][] sectionNames,
                                java.lang.String[][][] sectionContents)
```
This is a sample of what the input arrays should look like:

Torello.Build.Helper.PackageItems.java
Parameters:

packages - The list of packages as a String-Array

sectionNames - A Two-Dimensional String-Array that is parallel to the previous 'packages' parameter. Each sub-array here should contain the list of section names for the package in the parallel array.

sectionContents - A Three-Dimensional String-Array. The first dimension is parallel to both of the other two input array-parameters. Each of the sub-two-dimensional arrays merely / simply (this is not rocket-science) contains a list of classes (and interfaces, enum's, exceptions, etc...) that you want inside the "section" identified by the corresponding element of the 'sectionNames'-array.

Throws:

ParallelArrayException - If any of these three arrays aren't of equal lengths!

java.lang.NullPointerException - If any of these arrays contain any 'null' values

See Also:

rearrangeFrames

Code:
Exact Method Body:
1 2 3 4
this.rearrangeFrames = new RearrangePkgFrame.PackageItems (packages, sectionNames, sectionContents); return this;

upgrade

public void upgrade(StorageWriter sw)

After all parameters have been set with this "JavaDoc Upgrader" (builder)... this method should be invoked to do the processing. This runs the upgradeer for all Java Doc '.html' Files.

Parameters:

sw - This is the log.

Throws:

UpgradeException - An unchecked exception. (RuntimeException)

JavaDocError - If there any I/O errors, or other problems. Review the detailed messages provided - and possibly the Throwable.getCause().

Code:

Exact Method Body:

 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Fix Files in the ROOT & src-html/ Directory (add Favicon)
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 if (faviconImageFileName != null)
 {
     JDFiles .getHTMLFilesInRoot(rootJavaDocDirectory)
             .forEach((String javaDocHTMLFile) -> addFavicon(javaDocHTMLFile, sw));
     JDFiles .getSrcAsHTMLFiles(rootJavaDocDirectory)
             .forEach((String javaDocHTMLFile) -> addFavicon(javaDocHTMLFile, sw));
     JDFiles .getJavaPackageHTMLFiles(rootJavaDocDirectory)
             .forEach((String javaDocHTMLFile) -> addFavicon(javaDocHTMLFile, sw));
 }
 System.gc();

 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Upgrade & Hi-Lite JavaDoc Files
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 // Retrieve each and every Class, Interface, Enumerated-Type Java-Doc File into a Vector.
 JDFiles .getJavaClassHTMLFiles(rootJavaDocDirectory)
         .collect(Collectors.toCollection(Vector::new))
         .forEach((String jdHTMLFileName) -> run(jdHTMLFileName, sw));
 System.gc();

 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Clean up Package Summaries - if requested
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 // Perform some minor cleanups on the "Package Summaries" pages (the "DIV" elements
 // can skew it)
 if (packageSummaryCleaner != null)
     JDFiles.getPackageSummaryHTMLFiles(rootJavaDocDirectory)
         .forEach((String packageSummaryFileName) -> 
         {
             try {
                 sw.println("Reading File: " + C.BYELLOW + packageSummaryFileName + C.RESET);
                 String              pageAsStr   = FileRW.loadFileToString(packageSummaryFileName);
                 Vector<HTMLNode>    page        = HTMLPage.getPageTokens(pageAsStr, false);
                 String              dotDots     = StringParse.dotDots(packageSummaryFileName, rootJavaDocDirectory, FSEP);
    
                 sw.println("Inserting CSS Link");
                 Features.insertCSSLink(page, dotDots + JAVA_DOC_CSS_FILE_NAME);
                 sw.println("Cleaning Package Summary File: " + C.BYELLOW + packageSummaryFileName + C.RESET);            
                 CleanPackageSummaries.run(page, packageSummaryCleaner, VERBOSE_PRINT_STEPS ? sw : null);
                        
                 HiLiteDividers.run(page, packageSummaryFileName, hiLiter, VERBOSE_PRINT_STEPS ? sw : null);
                 sw.println("Writing File: " + C.BCYAN + packageSummaryFileName + C.RESET);
                 FileRW.writeFile(Util.pageToString(page), packageSummaryFileName);
             }
             catch (Exception e) 
             { throw new JavaDocError("Error cleaninig page" + packageSummaryFileName, e); }
         });


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // If the RearrangePkgFrame has been requested, do it
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 if (rearrangeFrames != null)
     try
         { RearrangePkgFrame.runAll(rearrangeFrames, rootJavaDocDirectory, sw); }
     catch (Exception e)
     {
         sw.println("Something went wrong in RearrangePkgFrame");
         throw new JavaDocError
             ("RearrangePkgFrame threw Exception.  See Throwable.getCause() for details", e);
     }
            

 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Write the Log to Disk, and Copy the CSS File
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 // Close the Log-File HTML
 if (logFile != null)
 {
     String temp = C.toHTML(sw.getString(), true, true, true).replace("\t", "        ");
     logFile.accept(temp + "\n\n");
     sw.erase();
 }

 // Write out the CSS Definitions Page to the Root Java-Doc Directory.
 writeCSSFileToJDDir();

run

public void run(java.lang.String jdFileName,
                StorageWriter sw)

This runs the Java-Doc Upgrade Mechanism for a single Java Doc '.html' file

Parameters:

jdFileName - This is the File-System File-Name of the Java-Doc HTML Web-Page File.

sw - This is a log. This parameter may not be null. If you do not require any log information, then simply set StorageWriter.sysOut to FALSE.

Throws:

UpgradeException - An unchecked exception. (RuntimeException)

JavaDocError - If there any I/O errors, or other problems. Review the detailed messages provided - and possibly the Throwable.getCause().

Code:

Exact Method Body:

 String file;

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

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

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

 if (VERBOSE_PRINT_STEPS) sw.println(
     "\n\n**************************************************************************" +
     '\n' + StringParse.rightSpacePad("Free Memory Available:", 35)     + C.BBLUE + freeMem  + C.RESET +
     '\n' + StringParse.rightSpacePad("Total Memory Available:", 35)    + C.BBLUE + totalMem + C.RESET
 );

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

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

 try
     { file = FileRW.loadFileToString(jdFileName);  }
 catch (IOException ioe)
 { 
     sw.println(C.BRED + "Failed to load File: " + C.RESET + C.BYELLOW + jdFileName + C.RESET + EXCC.toString(ioe));
     throw new JavaDocError(
         "Could not load Java Doc File [" + jdFileName + "] due to an IOException.\n" +
         "Please see getCause() throwable for details.\n" + EXCC.toString(ioe),
         ioe
     );
 }
 Vector<HTMLNode> fileVec = HTMLPage.getPageTokens(file, false);

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

 Ret2<String, String>    r2              = HELPER.getFullNameAndSourceFileName(fileVec);
 String                  cietFullName    = r2.a;
 String                  srcCodeFileName = rootSourceFileDirectory + r2.b;
 String                  dotDots         = StringParse.dotDots(jdFileName, rootJavaDocDirectory, FSEP);

 sw.println(
     StringParse.rightSpacePad("Fully-Qualified Name:", 35)     + C.BYELLOW + cietFullName + C.RESET + '\n' +
     StringParse.rightSpacePad("Built from Source-File:", 35)   + C.BYELLOW + srcCodeFileName + C.RESET + '\n' +
     StringParse.rightSpacePad("Relative-URL String:", 35)      + C.BYELLOW + dotDots + C.RESET
 );

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

 JavaDocHTMLFile jdhf;

 try
     { jdhf = new JavaDocHTMLFile(fileVec, jdFileName, sw); }
 catch (IOException ioe)
 {
     throw new JavaDocError(
         "Could not parse Java Doc HTML File [" + jdFileName + "] due to an IOException.\n" +
         "Please see getCause() throwable for details.\n" + EXCC.toString(ioe),
         ioe
     );
 }

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

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

 // *****************************************
 // ********* JavaSourceCodeFile ************
 // *****************************************
 String                  srcCodeAsStr;
 JavaSourceCodeFile      jscf;

 try
     { srcCodeAsStr = FileRW.loadFileToString(srcCodeFileName); }
 catch (IOException ioe)
 {
     throw new UpgradeException(
         "Unable to load file: [" + srcCodeFileName + "].\n" +
         "Currently Processing JavaDoc HTML Documentation Page: [" + jdFileName + "].\n" +
         "Please see getCause() throwable for details.\n" + EXCC.toString(ioe),
         ioe
     );
 }

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

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

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

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

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

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

 // *****************************************
 // ************** Main Stuff ***************
 // *****************************************

 boolean b1 = (hiLiteSourceCodeFileFilter == null)   || hiLiteSourceCodeFileFilter.test(cietFullName);
 boolean b2 = (summaryRemoveFilter == null)          || summaryRemoveFilter.test(cietFullName);
 boolean b3 = (hiLiteAllFieldsFilter == null)        || hiLiteAllFieldsFilter.test(cietFullName);
 boolean b4 = (hiLiteAllMethodsFilter == null)       || hiLiteAllMethodsFilter.test(cietFullName);
 boolean b5 = (cssTagsFilter == null)                || cssTagsFilter.test(cietFullName);

 if (b1) HiLiteSrcCodeFile.run(fileVec, jdFileName, srcCodeFileName, srcCodeAsStr, dotDots, jscf.name, (faviconImageFileName != null), hiLiter, VERBOSE_PRINT_STEPS ? sw : null);
 else    sw.println("HiLiteSourceCodeFile.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET);

 if (b2) CleanSummaries.removeAllDescriptionsFromSummaries(fileVec, VERBOSE_PRINT_STEPS ? sw : null);
 else    sw.println("CleanSummaries.removeAllDescriptionsFromSummaries(...)" + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET);

 EmbedTag.run(fileVec, jdFileName, embedTagIDTable, VERBOSE_PRINT_STEPS ? sw : null);
 HiLiteDividers.run(fileVec, jdFileName, hiLiter, VERBOSE_PRINT_STEPS ? sw : null);

 if (b3) HiLiteFields.run(fileVec, jscf, jdhf, jdFileName, srcCodeFileName, hiLiter, VERBOSE_PRINT_STEPS ? sw : null);
 else    sw.println("HiLiteFields.run(...)" + C.RESET + "\n\t" + C.BBLUE+ " was not called, as per request." + C.RESET);

 if (b4) HiLiteMethods.run(fileVec, jscf, jdhf, jdFileName, srcCodeFileName, hiLiter, VERBOSE_PRINT_STEPS ? sw : null);
 else    sw.println("HiLiteMethods.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET);

 SkewedParameters.run(fileVec, VERBOSE_PRINT_STEPS ? sw : null);

 if (b5) Colorize.run(fileVec, VERBOSE_PRINT_STEPS ? sw : null);
 else sw.println("Colorize.run(...)" + C.RESET + "\n\t" + C.BBLUE + " was not called, as per request." + C.RESET);

 // *****************************************
 // ************** More Stuff ***************
 // *****************************************

 sw.println("Other:");

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

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

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

 if (at != null) 
     at.accept(fileVec, jdFileName, srcCodeFileName, cietFullName, jscf, jdhf, sw);

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

 sw.println("Re-Writing File Back to Disk: " + C.BYELLOW + jdFileName + C.RESET);
 try
     { FileRW.writeFile(Util.pageToString(fileVec), jdFileName);  }
 catch (Exception e)
 { 
     sw.println(C.BRED + "Failed to write File: " + C.RESET + C.BYELLOW + jdFileName + C.RESET + ", Skipping...\n" + EXCC.toString(e));
     throw new UpgradeException("Failed to write File: " + jdFileName, e);
 }

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

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

main

public static void main(java.lang.String[] argv)
                 throws java.lang.Exception

SIMPLIFIED COMMAND LINE OPERATION.

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

argv[0]: (REQUIRED) The output java-doc directory
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:

 StorageWriter sw = new StorageWriter();
 Upgrade upgrader = new Upgrade(argv[0], "");

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

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

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

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

Class Upgrade

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

JAVA_DOC_CSS_FILE_NAME

FAVICON_FILE_NAME

rootJavaDocDirectory

rootSourceFileDirectory

faviconImageFileName

VERBOSE_PRINT_STEPS

logFile

embedTagIDTable

hiLiter

jdCSS

packageSummaryCleaner

at

rearrangeFrames

summaryRemoveFilter

hiLiteSourceCodeFileFilter

hiLiteAllMethodsFilter

hiLiteAllFieldsFilter

cssTagsFilter

Constructor Detail

Upgrade

Method Detail

turnOffVerboseProcessPrint

setLogFile

setLogFile

setSummaryRemoveFilter

setHiLiteSourceCodeFileFilter

setHiLiteAllMethodsFilter

setHiLiteAllFieldsFilter

setCSSTagsFilter

doNotRemoveSummaries

doNotHiLiteSourceCodeFiles

doNotHiLiteMethods

doNotHiLiteFields

doNotAddCSSTags

setEmbedTagsMapFile

setEmbedTagsMap

useHiLiteServerCache

setHiLiter

retrieveDefaultJDCSSFileFromJAR

setCustomJDCSSFile

doNotAddFavicon

setAdditionalTasks

setPackageSummaryCleaner

useDefaultPackageSummaryCleaner

setPackageFrames

upgrade

run

main