Class JDFiles

  • public class JDFiles
extends java.lang.Object
    JDFiles - Documentation.

    This class is built inside a list of the file-names that are usually generated by the JavaDoc Utility. There are only two methods, but they are capable of retrieving the list of Java Doc Generated HTML Class Documentation Files - along with any package and page index information pages as well. Both of these methods only require a single parameter - the name of the directory that was used to output the JavaDoc Tool files.

    IMPORTANT NOTE: It is absolutely not mandatory to use these two methods to retrieve the names of Java Documentation Files, but primarily, because this class has relatively good amounts of documentation itself (is that... 'self-aware?'), generally if trying to remember the names of files like 'package-info.html' along with the parameters to the file-system search methods, referencing this page might be of use if anybody were trying to use these JavaDoc Extension and Updgrade Java Classes.

    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Static Field: The methods in this class do not create any internal state that is maintained - but there is a single private & static field defined. This field is instantiated only once during the Class Loader phase (and only if this class shall be used), and serves as a data 'lookup' field (like a static constant). View this class' source-code in the link provided below to see internally used data.

    The only internally-defined private, static field defined in this class is a java.io.FilenameFilter



    • Field Detail

      • HTML_FILE_FILTER

        public static final java.io.FilenameFilter HTML_FILE_FILTER
        A Java Predicate that filters for '.html' files.
        Code:
        Exact Field Declaration Expression:
        1
2
        public static final FilenameFilter HTML_FILE_FILTER =
        (File dir, String name) -> name.trim().endsWith(".html");

    • Method Detail

      • getJavaClassHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getJavaClassHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files that JavaDoc generates for it's code documentation system, and returns the ones that are mapped to '.java' files. Classes in this Java-HTML package such as HTMLNode and FileNode make working witg HTML output, and file-system directory trees very easy.

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, null)
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM)
     .filter((String fileName) -> ! fileName.startsWith(rootJDOutDirName + "src-html" + File.separator))
     .filter((String fileName) -> ! fileName.startsWith(rootJDOutDirName + "index-files" + File.separator))
     .filter((String fileName) -> ! fileName.contains("package-summary.html"))
     .filter((String fileName) -> ! fileName.contains("package-tree.html"))
     .filter((String fileName) -> ! fileName.contains("package-frame.html"))
     .filter((String fileName) -> (StringParse.countCharacters(fileName, File.separator.charAt(0)) > 1));
         // The previous filter prevents any ".html" files that are in the root java-doc output directory,
         // ... and are not inside one of the packages.  If a class 'does not have a package' it will be skipped.

      • getSrcAsHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getSrcAsHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files which contain only the "Java Source Code" itself. The files that are returned in this Stream<String> are not "Code Documentation Web-Pages," but rather they are the "Java Source Code" itself, after some minor 'conversion' to turn them into HTML Web-Browser viewable files.

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files

        IMPORTANT: The 'javadoc' tool, by default, will not generate the "HTML-ized" source-code files. The creation of these files has to be specifically requested at the command-line using the switch -linksource. If this method is returning an empty Stream, make sure that the last invocation of jthe avadoc tool specified this switch, or there will not be a /jd-root-dir/src-file/ directory in the first place.
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
        1
2
3
4
         return FileNode
     .createRoot(rootJDOutDirName + "src-html" + File.separator)
     .loadTree(-1, HTML_FILE_FILTER, null)
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);

      • getJavaPackageHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getJavaPackageHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files that JavaDoc generates for it's code documentation system, and returns all of the 'package-summary', 'package-tree', and 'package-frame' files, and essentially, every file which is left out of the results returned for method: getJavaClassHTMLFiles(String)

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, null)
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM)
     .filter((String fileName) ->
         (! fileName.startsWith(rootJDOutDirName + "src-html" + File.separator)) &&
         (! fileName.startsWith(rootJDOutDirName + "index-files" + File.separator))
     )
     .filter((String fileName) ->
         fileName.contains("package-summary.html")   ||
         fileName.contains("package-tree.html")      ||
         fileName.contains("package-frame.html")     ||
         (StringParse.countCharacters(fileName, File.separator.charAt(0)) <= 1)
     );

      • getAllHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getAllHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files that JavaDoc generates for it's code documentation system, and returns all of them

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
        1
2
3
4
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, null)
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);

      • getPackageSummaryHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getPackageSummaryHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files that JavaDoc generates for it's code documentation system, and returns all files names "package-summary.html"

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files

        DESCRIPTION: A "Package Summary" Web-Page is the page that describes, briefly, the general goal of a Package in a Java JAR-File, or Java Tools Suite. It lists all classes present in the Package, and attempts to provide the first line of commenting for each class in an HTML Table with links to that class.
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
        1
2
3
         return JDFiles
     .getJavaPackageHTMLFiles(rootJDOutDirName)
     .filter((String fileName) -> fileName.contains("package-summary.html"));

      • getPackageFrameHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getPackageFrameHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files that JavaDoc generates for it's code documentation system, and returns all files names "package-frame.html"

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files

        DESCRIPTION: A "Package Frame" Web-Page is the page that lists all classes present in the Package, and simply provides links to each class.
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
        1
2
3
         return JDFiles
     .getJavaPackageHTMLFiles(rootJDOutDirName)
     .filter((String fileName) -> fileName.contains("package-frame.html"));

      • getHTMLFilesInRoot

        public static java.util.stream.Stream<java.lang.String> getHTMLFilesInRoot​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files in the Base JavaDoc Output Directory. This is usually something simple like 'javadoc/'

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
        1
2
3
4
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(1, HTML_FILE_FILTER, null)
     .flattenJustFiles(FileNode.RetTypeChoice.FULLPATH_STREAM);

      • getPackageTreeHTMLFiles

        public static java.util.stream.Stream<java.lang.String> getPackageTreeHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method reads in the HTML files that JavaDoc generates for it's code documentation system, and returns all files names "package-tree.html"

        NOTE: This method accepts a directory name from the local file system. This must be the name of the directory to which the last call to javadoc left it's output HTML files

        DESCRIPTION: A "Package Tree" Web-Page is the page that lists all classes present in the Package, and builds an Object Hierarchy of those classes. Links are included to each class in this Object-Oriented Inheritance Hierarchy Tree.
        Parameters:
        rootJDOutDirName - This should be the directory-name (as a String) of the last javadoc output directory. (Usually this is 'javadoc/')
        Returns:
        This will return the list of files as a Java Stream<String>.
        Code:
        Exact Method Body:
        1
2
3
         return JDFiles
     .getJavaPackageHTMLFiles(rootJDOutDirName)
     .filter((String fileName) -> fileName.contains("package-tree.html"));