Package Torello.JavaDoc
Class Upgrade
- java.lang.Object
-
- Torello.JavaDoc.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 withJava 14 (LTS)
and withJava 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 theJava 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 JavaCLASSPATH
environment variable. The link below is a link to theJava 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 completeJava 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-linemain(String[])
method available. Recognize that the CLI version of this class does not initialize any of the fields (except possibly theHiLiter 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 theUpgrade
Tool's initialization "hamburger stack". The last method invoked on this stack is therun()
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);
Hi-Lited Source-Code:- View Here: Torello/JavaDoc/Upgrade.java
- Open New Browser-Tab: Torello/JavaDoc/Upgrade.java
-
-
Field Summary
Source-Code & HTML Root Directories Modifier and Type Field String
rootJavaDocDirectory
String[]
rootSourceFileDirectories
Primary Configuration's Modifier and Type Field Consumer<JavaDocHTMLFile>
extraTasks
String
faviconImageFileName
protected Vector<HTMLNode>
headerTags
protected HiLiter
hiLiter
protected String
jdCSS
protected Torello.JavaDoc.HTMLProcessors.LinksChecker
linksChecker
protected Appendable
logFile
protected Consumer<Vector<HTMLNode>>
packageSummaryCleaner
Map<String,String>
projectGlobalEmbedTagsMap
protected boolean
VERBOSE_PRINT_STEPS
HiLiting Decision Predicate's Modifier and Type Field protected Predicate<String>
hiLiteAllAnnotationElemsFilter
protected Predicate<String>
hiLiteAllConstructorsFilter
protected Predicate<String>
hiLiteAllEnumConstantsFilter
protected Predicate<String>
hiLiteAllFieldsFilter
protected Predicate<String>
hiLiteAllMethodsFilter
protected Predicate<String>
hiLiteSourceCodeFileFilter
Details Removal Predicate's Modifier and Type Field protected Predicate<String>
removeAllAEDetailsFilter
protected Predicate<String>
removeAllConstructorDetailsFilter
protected Predicate<String>
removeAllDetailsFilter
protected Predicate<String>
removeAllECDetailsFilter
protected Predicate<String>
removeAllFieldDetailsFilter
protected Predicate<String>
removeAllMethodDetailsFilter
More Decision Predicate's Modifier and Type Field protected Predicate<String>
cssTagsFilter
protected Predicate<String>
summaryRemoveFilter
protected Predicate<String>
validateHTMLFilter
Balance & Statistics Modifier and Type Field protected boolean
checkBalance
Stats
stats
Tab Policy Settings Modifier and Type Field UnaryOperator<String>
indentor
protected Boolean
relativeOrAbsolute
protected int
spacesPerTab
String Constants Modifier and Type Field static String
FAVICON_FILE_NAME
static String
JAVA_DOC_CSS_FILE_NAME
static String
JAVA_SCRIPT_FILE_NAME
Recently Made Public Modifier and Type Field static char
FSEP
static Runtime
rt
-
Constructor Summary
Constructors Constructor Upgrade(String rootJavaDocDirectory, String... rootSourceFileDirectories)
-
Method Summary
Main Methods Modifier and Type Method TreeSet<String>
getPackageCIETList(String packageName)
static void
main(String[] argv)
static String
retrieveDefaultJDCSSFileFromJAR()
static String
retrieveDefaultJDUJSFileFromJAR()
Stats
upgrade()
Set Primary Configurations Modifier and Type Method Upgrade
runLinksChecker()
Upgrade
setCustomJDCSSFile(String CSSFileAsAString)
Upgrade
setExtraTasks(Consumer<JavaDocHTMLFile> extraTasks)
Upgrade
setFaviconFileFormat(IF faviconFileFormat)
Upgrade
setLogFile(Appendable logFile)
Upgrade
setLogFile(String logFileName)
Upgrade
setPackageSummaryCleaner(Consumer<Vector<HTMLNode>> packageSummaryCleaner)
Upgrade
setProjectGlobalEmbedTagsMap(Map<String,String> tagIDMap)
Upgrade
setProjectGlobalEmbedTagsMapFile(String tagIDMapFileName)
Upgrade
turnOnVerboseProcessPrint()
Upgrade
useDefaultPackageSummaryCleaner()
Set Code HiLiter Modifier and Type Method Upgrade
setHiLiter(HiLiter hiLiter)
Upgrade
useHiLiteServerCache(HiLiteMe.Cache cache)
Set HiLiting Decision Predicate's Modifier and Type Method Upgrade
setHiLiteAllAnnotationElemsFilter(Predicate<? super String> annotationNameFilter)
Upgrade
setHiLiteAllConstructorsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiteAllEnumConstantsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiteAllFieldsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiteAllMethodsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setHiLiteSourceCodeFileFilter(Predicate<? super String> cietNameFilter)
Set Detail Removal Decision Predicate's Modifier and Type Method Upgrade
setRemoveAllAEDetailsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setRemoveAllConstructorDetailsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setRemoveAllDetailsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setRemoveAllECDetailsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setRemoveAllFieldDetailsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setRemoveAllMethodDetailsFilter(Predicate<? super String> cietNameFilter)
Turn HiLiting Decision Predicate's On & Off Modifier and Type Method Upgrade
doNotHiLiteAnnotationElems()
Upgrade
doNotHiLiteFields()
Upgrade
doNotHiLiteMethods()
Upgrade
doNotHiLiteSourceCodeFiles()
Upgrade
hiLiteConstructors()
Upgrade
hiLiteEnumConstants()
Additional Decision Predicate's Modifier and Type Method Upgrade
doNotAddCSSTags()
Upgrade
doNotRemoveSummaries()
Upgrade
doNotValidateHTML()
Upgrade
setCSSTagsFilter(Predicate<? super String> cietNameFilter)
Upgrade
setSummaryRemoveFilter(Predicate<? super String> cietNameFilter)
Upgrade
setValidateHTMLFilter(Predicate<? super String> cietNameFilter)
Balance & Statistics Modifier and Type Method Upgrade
setCheckBalance(boolean checkBalance)
Setting a Tab-Replacement Policy Modifier and Type Method Upgrade
setTabsPolicy(int spacesPerTab, boolean relativeOrAbsolute)
Adding HTML <HEAD> Tags Modifier and Type Method Upgrade
addHeaderBlocks(Vector<HTMLNode> headerStuff)
Upgrade
addHeaderTags(Iterable<TagNode> headerTags)
Run the ( protected
) Configuration-Predicate'sModifier and Type Method boolean
testCSSTagsFilter(String s)
boolean
testHiLiteAllAnnotationElemsFilter(String s)
boolean
testHiLiteAllConstructorsFilter(String s)
boolean
testHiLiteAllEnumConstantsFilter(String s)
boolean
testHiLiteAllFieldsFilter(String s)
boolean
testHiLiteAllMethodsFilter(String s)
boolean
testHiLiteSourceCodeFileFilter(String s)
boolean
testRemoveAllAEDetailsFilter(String s)
boolean
testRemoveAllConstructorDetailsFilter(String s)
boolean
testRemoveAllDetailsFilter(String s)
boolean
testRemoveAllECDetailsFilter(String s)
boolean
testRemoveAllFieldDetailsFilter(String s)
boolean
testRemoveAllMethodDetailsFilter(String s)
boolean
testSummaryRemoveFilter(String s)
boolean
testValidateHTMLFilter(String s)
Source Code Parser: JavaParser™ or com.sun.source.tree
Modifier and Type Method byte
parserInstanceChoice()
Upgrade
setParserInstanceChoice(byte choice)
-
-
-
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 thisString
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 afavicon
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 providedStorageWriter
when this field is set to TRUE. By default, this field is set FALSE
NOTE: If no instance ofStorageWriter
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 internalMessager
instance, this instance ofAppendable
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 directoryTorello/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-systemtext-file
using this map.
The'embedTagIDTable'
is a really simple 'Map' that translates an'<EMBED>'
element'sDATA-FILE-ID
to an'.html'
file-name (that you have written) on the file-system. TheEmbed Tags Map File
used by thisLibrary's Build Script
may be viewed below, as an example. This is an exhaustive list of all Externally-Linked HTML Pages for theJava 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<>();
-
hiLiter
protected HiLiter hiLiter
The CodeHiLiter
instance. The defaultHiLiter
is used, unlesssetHiLiter
is called.- See Also:
useHiLiteServerCache(HiLiteMe.Cache)
,setHiLiter(HiLiter)
- Code:
- Exact Field Declaration Expression:
protected HiLiter hiLiter = HiLiter.getDefault(null, "vim", "native");
-
jdCSS
protected java.lang.String jdCSS
This should be the contents of the intendedCSS 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: ThisCSS File
is only useable if the user has not invokeddoNotAddCSSTags()
. If the Upgrader is prohibited from addingCSS Tags
to Java-Doc generated web-pages, then theCSS Rules
will be not be useable by the browser.
NOTE: The defaultCSS Rules
for the CSSCLASS
andID
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 defaultCSS 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 pagespackage-summary.html
for a particular JavaDoc package, theclasses
andinterfaces
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 ofConsumer<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.
Thisjava.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 theTorello.HTML
and theNodeSearch
packages. In any case, just about everything you would need to know about a Java Doc HTML page is provided in the parameters of theJavaDocHTMLFile
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 flagboolean
is, by default, set toTRUE
. ThisUpgrade
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" inclass 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 anHREF=...
instead of aSRC=...
, 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 HTMLTagNode'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 canonicalURL
, some general'keywords'
, or possibly company, author, contact, or images-links, then providing those tags (as instances ofTagNode
) 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.- 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;
-
spacesPerTab
protected int spacesPerTab
The number of space-characters (' '
) used to replace a tab-character ('\t'
)- See Also:
setTabsPolicy(int, boolean)
- Code:
- Exact Field Declaration Expression:
protected int spacesPerTab = 4;
-
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 whichclass, interface, enum
etc...'.java'
Source-Code Files need to avoid having their 'Summary Descriptions' removed. The Java Doc Tool inserts summaries into aMethod Summaries
,Field Summaries
, andConstructor 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 identifyingclasses, 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:
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.
TheDo Not HiLite Source-Code Files Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
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 aStrFilter
, and passed tosetHiLiteSourceCodeFileFilter(Predicate)
Skip All Source-File HiLiting Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLited 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:
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 allMethod's
are automatically hilited.
TheDo Not HiLite Methods Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which no'Method Body'
HiLiting is performed. The file is loaded into aStrFilter
, and passed tosetHiLiteAllMethodsFilter(Predicate)
Skip All Methods HiLiting Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLite 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:
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 allField's
are automatically hilited.
TheDo Not HiLite Fields Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which no'Field Declaration'
HiLiting is performed. The file is loaded into aStrFilter
, and passed tosetHiLiteAllFieldsFilter(Predicate)
Skip All Fields HiLiting Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLite 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:
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.
TheHiLite Constructors Filter
for thisJar Distribution Package
can be viewed here, below (as an example). TheClasses
listed in this file are all the classes for which'Constructor Declaration'
HiLiting is performed. The file is loaded into aStrFilter
, and passed tosetHiLiteAllConstructorsFilter(Predicate)
HiLite All Constructors Text File
The above file is loaded into thisPredicate<String>
by calling:
StrFilter.strListKEEP_NOIOE(String, boolean)
TheHiLite Constructor Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- 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 whichAnnotation '.html'
Java-Doc Files will have their element-declarations hilited and inserted in their respective JavaDoc'.html'
pages. By default allAnnotation Element's
are automatically hilited.
NOTE: Only JavaAnnotations (@interface)
files allow these elements to be declared. The vast majority of JavaDoc HTML Pages will not have a details section forAnnotation Members / Elements
.
TheHiLite Annotation-Elements Filter
is loaded into thisPredicate<String>
by calling:
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLite Annotation Element
procedure is the one which creates segments on your Java Doc Pages that look like:- 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 whichEnumeration '.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 anenum's
constants, then this procedure could be of use.
AHiLite Enum-Constants Filter
is loaded into thisPredicate<String>
by calling:
HiLite All Constants Text File
StrFilter.strListREJECT_NOIOE(String, boolean)
TheHiLite Constant Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- 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.
TheInsert CSS Tags
procedure is the one which createsCSS CLASS
attributes in your Java Doc Pages that look:
To see the complete list ofCSS CLASS
attributes that are added to a Java Doc'.html'
File, please review classCSSTags
.
The defaultCSS 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
ThePredicate<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 ofFALSE
is assigned to the fieldcheckBalance
, then anyPredicate
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 isfalse
, thisPredicate
is effectively ignored.
FINALLY: The results of thisPredicate
do not affect the validation of externally-linked<EMBED CLASS='external-html'>
files. If you would like avoid validating those files, you must set thecheckBalance
flag toFALSE
. 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 packageTorello.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 forMethod
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 forConstructor
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 forField
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 forMethod
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 manyEnum 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 forAnnotation Element
declarations. By default, this filter is inactive.
NOTE: Only JavaAnnotations (@interface)
files allow these elements to be declared. The vast majority of JavaDoc HTML Pages will not have a details section forAnnotation 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-PredicatesummaryRemoveFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
summaryRemoveFilter
- Code:
- Exact Method Body:
return summaryRemoveFilter.test(s);
-
testHiLiteSourceCodeFileFilter
public boolean testHiLiteSourceCodeFileFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatehiLiteSourceCodeFileFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
hiLiteSourceCodeFileFilter
- Code:
- Exact Method Body:
return hiLiteSourceCodeFileFilter.test(s);
-
testHiLiteAllMethodsFilter
public boolean testHiLiteAllMethodsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatehiLiteAllMethodsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
hiLiteAllMethodsFilter
- Code:
- Exact Method Body:
return hiLiteAllMethodsFilter.test(s);
-
testHiLiteAllFieldsFilter
public boolean testHiLiteAllFieldsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatehiLiteAllFieldsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
hiLiteAllFieldsFilter
- Code:
- Exact Method Body:
return hiLiteAllFieldsFilter.test(s);
-
testHiLiteAllConstructorsFilter
public boolean testHiLiteAllConstructorsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatehiLiteAllConstructorsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
hiLiteAllConstructorsFilter
- Code:
- Exact Method Body:
return hiLiteAllConstructorsFilter.test(s);
-
testHiLiteAllAnnotationElemsFilter
public boolean testHiLiteAllAnnotationElemsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatehiLiteAllAnnotationElemsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
hiLiteAllAnnotationElemsFilter
- Code:
- Exact Method Body:
return hiLiteAllAnnotationElemsFilter.test(s);
-
testHiLiteAllEnumConstantsFilter
public boolean testHiLiteAllEnumConstantsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatehiLiteAllEnumConstantsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
hiLiteAllEnumConstantsFilter
- Code:
- Exact Method Body:
return hiLiteAllEnumConstantsFilter.test(s);
-
testCSSTagsFilter
public boolean testCSSTagsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicatecssTagsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- 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-PredicatevalidateHTMLFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- 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 haveEnum 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: OnlyAnnotations (@interface)
will ever haveAnnotation Element's
.- See Also:
removeAllAEDetailsFilter
- Code:
- Exact Method Body:
this.removeAllAEDetailsFilter = RAW_TYPES_FIX(cietNameFilter); return this;
-
testRemoveAllDetailsFilter
public boolean testRemoveAllDetailsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicateremoveAllDetailsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
removeAllDetailsFilter
- Code:
- Exact Method Body:
return removeAllDetailsFilter.test(s);
-
testRemoveAllMethodDetailsFilter
public boolean testRemoveAllMethodDetailsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicateremoveAllMethodDetailsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
removeAllMethodDetailsFilter
- Code:
- Exact Method Body:
return removeAllMethodDetailsFilter.test(s);
-
testRemoveAllConstructorDetailsFilter
public boolean testRemoveAllConstructorDetailsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicateremoveAllConstructorDetailsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
removeAllConstructorDetailsFilter
- Code:
- Exact Method Body:
return removeAllConstructorDetailsFilter.test(s);
-
testRemoveAllFieldDetailsFilter
public boolean testRemoveAllFieldDetailsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicateremoveAllFieldDetailsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
removeAllFieldDetailsFilter
- Code:
- Exact Method Body:
return removeAllFieldDetailsFilter.test(s);
-
testRemoveAllECDetailsFilter
public boolean testRemoveAllECDetailsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicateremoveAllECDetailsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
removeAllECDetailsFilter
- Code:
- Exact Method Body:
return removeAllECDetailsFilter.test(s);
-
testRemoveAllAEDetailsFilter
public boolean testRemoveAllAEDetailsFilter(java.lang.String s)
Runs the (private
) Configuration-PredicateremoveAllAEDetailsFilter
- Parameters:
s
- Any Java-String
to test against thisPredicate
.- Returns:
- This
Predicate's
results after applying it to parameter's'
. - See Also:
removeAllAEDetailsFilter
- Code:
- Exact Method Body:
return removeAllAEDetailsFilter.test(s);
-
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 internalMessager
instance, this instance ofAppendable
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 ofAppendable
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, anUpgradeException
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 JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being modified.
ThePredicate
should returnTRUE
if you would like to avoid removing theField
andMethod
Summary Text from theField Summaries
andMethod 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 JavaPredicate
using either:
Cleaned Summaries look as in the picture below:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- 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 JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the original Java Source-Code ('.java'
file) HiLited, andFALSE
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 JavaPredicate
using either:
TheHiLited Source Code File
procedure is the one which creates links on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- 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 allMethod's
are automatically hilited.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Method Bodies HiLited, andFALSE
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 JavaPredicate
using either:
TheHiLite Method Body
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- 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 allField's
are automatically hilited.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Field Declarations HiLited, andFALSE
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 JavaPredicate
using either:
TheHiLite Field Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- 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 specificCIET's
hilited - using this method.. Alternatively, you may invokehiLiteConstructors()
to have all constructor bodies (for allCIET's
) hilited and inserted into Java Doc Pages.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Constructor Declarations HiLited, andFALSE
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 JavaPredicate
using either:
TheHiLite Constructor Declaration
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass
orEnum
.- 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 JavaAnnotations
) will have their element-declarations hilited, and the hilited-code inserted into the JavaDoc Page. By default allAnnotation Element's
are automatically hilited.
NOTE: Only JavaAnnotations (@interface)
files allow these elements to be declared. The vast majority of JavaDoc HTML Pages will not have a details section forAnnotation Members / Elements
.
The filter-parameter ('annotationNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaAnnotation
whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Element Declarations HiLited, andFALSE
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 JavaPredicate
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 thisPredicate
, such a mistake will be gracefully ignored.
TheHiLite Annotation Element
procedure is the one which creates segments on your Java Doc Pages that look like:
- Parameters:
annotationNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of a JavaAnnotation
.- 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 theEnumeration Constants
for a specific'enum'
hilited - using this method.. Alternatively, you may invokehiLiteEnumConstants()
to have the all constants declared in any / allenum's
hilited and inserted into their respective Java Doc Pages.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a Java'enum'
whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see the Enumeration Constant Declarations HiLited, andFALSE
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 JavaPredicate
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 thisPredicate
, such a mistake will be gracefully ignored.
TheHiLite Enumeration Constant
procedure is the one which creates segments on your Java Doc Pages that look like:- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of a JavaEnum 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 ofCSS 'CLASS'
andCSS '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 haveCSS Tags
inserted.
The filter-parameter ('cietNameFilter'
) that needs to be passed here is just a JavaPredicate<String>
. ThisPredicate's 'test(String)'
method will receive the fully-qualified name of a JavaClass, Interface,
orEnum
(CIET) whose source-code documentation-file is being Code-HiLited.
ThePredicate
should returnTRUE
if you would like to see CSS Tags inserted into the HTML, andFALSE
if the Upgrader should skip insertingCSS Tags
into this CIET.
TheInsert CSS Tags
procedure is the one which createsCSS 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 JavaPredicate
using either:
The defaultCSS File
used by this upgrader may be viewed here:
Default CSS File- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- 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 returnTRUE
orFALSE
, 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 thisUpgrade
Configuration class. When this flag is set toFALSE
its value 'takes precedence' over anything that is returned by thevalidateHTMLFilter
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 thesetCheckBalance(false)
Configuration Method, the subsequent call tosetValidateHTMLFilter
is no different than a "No Op", it has no effect on the final processing.- Parameters:
cietNameFilter
- The file-name filter. Thisjava.lang.Predicate<String>
needs to accept or reject the fully qualified name of aClass, Interface,
orEnum
.- 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 filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have theirSummaries
(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 aMethod
orField
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 theMethod Summaries
orField 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 filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have their fullSource 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;
-
doNotHiLiteMethods
public Upgrade doNotHiLiteMethods()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have theirMethod Bodies
HiLited.- See Also:
hiLiteAllMethodsFilter
,setHiLiteAllMethodsFilter(Predicate)
- Code:
- Exact Method Body:
this.hiLiteAllMethodsFilter = ALWAYS_FALSE; return this;
-
doNotHiLiteFields
public Upgrade doNotHiLiteFields()
This will set a filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will have theirField Declarations
HiLited.- See Also:
hiLiteAllFieldsFilter
,setHiLiteAllFieldsFilter(Predicate)
- Code:
- Exact Method Body:
this.hiLiteAllFieldsFilter = ALWAYS_FALSE; return this;
-
hiLiteConstructors
public Upgrade hiLiteConstructors()
Differing fromFields
andMethods
, constructors in an upgraded Java-Doc Page are not automatically hilited. You need to explicity ask the upgrader to hiliteConstructor Bodies
. This method will indicate to the upgrader to hilite theConstructor Bodies
for allclasses
andenums
that it encounters.
This will set a filterPredicate
that returnsTRUE
for everyClass
orEnum
. If this method is used, then all of the Java-Doc Upgraded Pages will have theirConstructor Bodies
HiLited.- See Also:
hiLiteAllConstructorsFilter
,setHiLiteAllConstructorsFilter(Predicate)
- Code:
- Exact Method Body:
this.hiLiteAllConstructorsFilter = ALWAYS_TRUE; return this;
-
doNotHiLiteAnnotationElems
public Upgrade doNotHiLiteAnnotationElems()
This will set a filterPredicate
that returnsFALSE
for everyAnnotation
. If this method is used, then none of the Java-Doc Upgraded Pages (forAnnotations
) will have theirElement Declarations
HiLited. (If they had any such declarations in the first place!)- See Also:
hiLiteAllAnnotationElemsFilter
,setHiLiteAllAnnotationElemsFilter(Predicate)
- Code:
- Exact Method Body:
this.hiLiteAllAnnotationElemsFilter = ALWAYS_FALSE; return this;
-
hiLiteEnumConstants
public Upgrade hiLiteEnumConstants()
Differing fromFields
andMethods
, enumeration constants in an upgraded Java-Doc'enum'
Page are not automatically hilited. You need to explicity ask the upgrader to hiliteConstant Declarations
. This method will indicate to the upgrader to hilite theEnumeration Constants
for allenum's
that it encounters.
This will set a filterPredicate
that returnsTRUE
for everyenum
about which it is queryied. If this method is used, then all of the Java-Doc Upgraded'enum'
Pages will have theirEnumeration 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 anenum'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 filterPredicate
that returnsFALSE
for everyClass, Interface
orEnum
. If this method is used, then none of the Java-Doc Upgraded Pages will haveCSS 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;
-
doNotValidateHTML
public Upgrade doNotValidateHTML()
When this method is invoked, the HTML for all Java Doc Class Files will avoid the HTML Validation Process.- See Also:
validateHTMLFilter
,setValidateHTMLFilter(Predicate)
- Code:
- Exact Method Body:
this.validateHTMLFilter = ALWAYS_FALSE; return this;
-
setProjectGlobalEmbedTagsMapFile
public Upgrade setProjectGlobalEmbedTagsMapFile (java.lang.String tagIDMapFileName)
Sets aProject Global Embed Tag ID Map
using atext 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-systemtext-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.
TheEmbed 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 theProject Global Embed Tag ID Map
using a Javajava.util.Map<tring, String>
. The firstGeneric 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;
-
useHiLiteServerCache
public Upgrade useHiLiteServerCache(HiLiteMe.Cache cache)
Convenience Method
Invokes:HiLiter.getDefault(HiLiteMe.Cache, String, String)
And-Then:setHiLiter(HiLiter)
- Code:
- Exact Method Body:
setHiLiter(HiLiter.getDefault(cache, "vim", "native")); return this;
-
setHiLiter
public Upgrade setHiLiter(HiLiter hiLiter)
Tells this Upgrader to use a particular'HiLiter'
. The defaultHiLiter
is used if this method isn't invoked. ReplacementHiLiter's
are better explained by theHiLiter
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 UpgradeCSS File
as aString
.
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 theString
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 ajava.lang.String
, and saving thatString
to a file). Once the standard-issue CSS has been modified to fit your needs, using the new-updated definitions is done by invokingsetCustomJDCSSFile(String)
.
NOTE: The actualCLASS
andID
tags inserted by this tool cannot be changed - only the definitions (fonts, colors, & styles) may be modified. The actual'.css'
file retrieved (as ajava.lang.String
) contains much explanation and commenting for each of theCLASS
andID
tags defined on the page. Again, save thisString
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 methodsetCustomJDCSSFile(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 forclass CSSTags
also has a detailed explanation for each of theCLASS
andID
definitions inserted by this upgrader tool. Thisclass
should also be reviewed if the comments and documentation included in theString
/ file returned by this method are insufficient for understanding what is happening.
The defaultCSS File
used by this upgrader may be viewed here:
Default CSS File- Returns:
- A
CSS File
which utilizes the addedCSS
CSSTags
CLASSES
. The actual file is read from disk, and returned as aString
. - 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 CSSCLASS
Names andID
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 changeCLASS
orID
names of the CSS tags that are inserted.
NOTE: The Upgrader Tool's methodretrieveDefaultJDCSSFileFromJAR()
will return the complete CSS definition'.css'
file. Review that method's documentation for more information. Save thatjava.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 ajava.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 theCSS File
to be loaded into aString
, 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 theCSS File
as ajava.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 outputjavadoc/
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-fieldheaderTags
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-fledgedVector<HTMLNode>
. This entireVector
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 theLinksChecker
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 receivesTRUE
, 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 index13
in a line-of-code, and the value passed to'spacesPerTab'
were4
, then the number of spaces inserted would be3
. This is because precisely3
spaces would skip to index16
, which happens to be the next-highest rounded-multiple of4
.
When this parameter receivesFALSE
, a tab-character is always replaced by the exact number of space-characters specified byspacesPerTab
.- Throws:
java.lang.IllegalArgumentException
- If a number less than1
or greater than20
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 isTRUE
.- 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 theDoclet
feature, when the Upgrader is provided anExtra 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 classJavaDocHTMLFile
provides many accessor methods to retrieve the Summary Tables, and the HTML Details - along with reflection-classes about theMethod
'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 thisConsumer<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 theCIET
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;
-
useDefaultPackageSummaryCleaner
public Upgrade useDefaultPackageSummaryCleaner()
The default Package Description Summary Page Cleaner.- Returns:
'this' Upgrade
instance - for invocation-chaining.- See Also:
packageSummaryCleaner
- Code:
- Exact Method Body:
this.packageSummaryCleaner = CleanPackageSummaries::defaultCleaner; 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 Packagecom.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:argv[0]:
(REQUIRED) The output java-doc directoryargv[1]:
(OPTIONAL) TheHiLiteMe
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");
-
-