Class JDFiles

  • public class JDFiles
extends java.lang.Object
    Retrieve Java Doc HTML Files from the Java Doc output directory.

    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 methods to retrieve the names of Java Documentation Files in order to perform an upgrade. Primarily, because this class has a relatively good amount of explanation itself, the code is provided to demonstrate how to retrieve these files into Java-Memory using the Torello.Java class FileNode.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.
    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 11 Method(s), 11 declared static
    • 2 Field(s), 2 declared static, 2 declared final


    • Method Summary

       
      Retrieve all User-Provided <EMBED> Tag-Map Files
      Modifier and Type Method
      static Stream<String> allLocalEmbedTagMapFiles​(String rootSrcCodeDirName)
       
      Retrieve every '.html' File in the JavaDoc Directory Tree
      Modifier and Type Method
      static Stream<String> getAllHTMLFiles​(String rootJDOutDirName)
       
      Retrieve '.html' Files from only the Root JavaDoc Directory
      Modifier and Type Method
      static Stream<String> getHTMLFilesInRoot​(String rootJDOutDirName)
       
      Retrieve all CIET/Type '.html' Files in the JavaDoc Directory Tree
      Modifier and Type Method
      static Stream<String> getJavaClassHTMLFiles​(String rootJDOutDirName)
       
      Retrieve all CIET/Type '.html' Files, but organize them by Package
      Modifier and Type Method
      static TreeMap<String,
           ​Vector<String>>      		 getJavaClassHTMLFilesByPackage​(String rootJDOutDirName)
       
      Retrieve all 'package-*.html' Files
      Modifier and Type Method
      static Stream<String> getJavaPackageHTMLFiles​(String rootJDOutDirName)
       
      Retrieve all 'package-frame.html' and 'package-summary.html' Files
      Modifier and Type Method
      static Stream<String> getFrameSummaryHTMLFiles​(String rootJDOutDirName)
       
      Retrieve all 'package-frame.html' Files
      Modifier and Type Method
      static Stream<String> getPackageFrameHTMLFiles​(String rootJDOutDirName)
       
      Retrieve all 'package-summary.html' Files
      Modifier and Type Method
      static Stream<String> getPackageSummaryHTMLFiles​(String rootJDOutDirName)
       
      Retrieve all 'package-tree.html' Files
      Modifier and Type Method
      static Stream<String> getPackageTreeHTMLFiles​(String rootJDOutDirName)
       
      Retrieve all linked 'src-html/' CIET/Type '.html' Files
      Modifier and Type Method
      static Stream<String> getSrcAsHTMLFiles​(String rootJDOutDirName)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • 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:
         public static final FilenameFilter HTML_FILE_FILTER =
         (File dir, String name) -> name.trim().endsWith(".html");

      • DIRS_TO_SKIP

        🡅  🡇  ⇈  ⮫ 
        public static final java.io.FileFilter DIRS_TO_SKIP
        A Java Predicate that avoids directories that contain extranneous files.
        Code:
        Exact Field Declaration Expression:
         public static final FileFilter DIRS_TO_SKIP = (File dir) -> StrCmpr.equalsNAND
         (dir.getName(), "src-html", "index-files", "doc-files", "hilite-files" );

    • 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>.
        See Also:
        HTML_FILE_FILTER, DIRS_TO_SKIP, FileNode, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
     .prune(
         (FileNode fn) -> StrCmpr.equalsNAND
             (fn.name, "package-summary.html", "package-tree.html", "package-frame.html"),
         true
     )
     // This 'prune' eliminates HTML files in the *ROOT* Java-Doc directory
     .prune(
         (FileNode fn) -> ! rootJDOutDirName.equals(fn.getParentPathName()),
         true
     )
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);

      • getJavaClassHTMLFilesByPackage

        🡅  🡇  ⇈  ⮫ 
        public static java.util.TreeMap<java.lang.String,​java.util.Vector<java.lang.String>> getJavaClassHTMLFilesByPackage​
            (java.lang.String rootJDOutDirName)
        This method returns the exact same files as getJavaClassHTMLFiles(String), but each file returned has been sorted into a specific 'bucket' based on which Java Package the CIET (class, inteface, enumerated-type, record etc...) HTML file belongs.
        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, sorted by 'Package Name' - where the package is merely determined by the directory-name where the file was found.
        ElementContents
        TreeMap 'key' The directory-name of the Java-Doc HTML-Directory containing the CIET Java Doc HTML Files for a specific package. (NOTE: This is different than the actual 'Package Name')
        TreeMap 'value' A Vector of file-name's (each as a String) of each Java Doc generated HTML file for a CIET in the specific package.
        See Also:
        HTML_FILE_FILTER, DIRS_TO_SKIP, FileNode, FileNode.getParentPathName(), FileNode.flattenJustDirs()
        Code:
        Exact Method Body:
         TreeMap<String, Vector<String>> ret = new TreeMap<>();

 // These are files usually found in a Package-Directory.  These cannot be processed by
 // the class "MainFilesProcessor".  These files are not for CIET/Types (specific class
 // JD Files), but rather if/when these files need to be modified they are handled by the
 // "ExtraFilesProcessor"

 FileNodeFilter TYPE_HTML_FILES = (FileNode fn) -> StrCmpr.equalsNAND
     (fn.name, "package-summary.html", "package-tree.html", "package-frame.html");

 FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
     .flattenJustDirs()
     .forEach((FileNode packageDirFN) ->
     {
         // The Full-Path Directory name of a single Java Package
         String packageDir = packageDirFN.getFullPathName();

         // The root 'javadoc/' directory doesn't have any of the Java class files
         if (packageDir.equals(rootJDOutDirName)) return;

         // Retrieve all CIET/Type Web-Pages for a single package-directory
         Vector<String> cietFileNames = packageDirFN.getDirContentsFiles
             (RetTypeChoice.SORTED_FILENAME_VECTOR, TYPE_HTML_FILES);

         // Sometimes a Java-Package doesn't have any files in it.  Skip those dirs.
         if (cietFileNames.size() > 0) ret.put(packageDir, cietFileNames);
     });

 return ret;

      • allLocalEmbedTagMapFiles

        🡅  🡇  ⇈  ⮫ 
        @Deprecated
ublic static java.util.stream.Stream<java.lang.String> allLocalEmbedTagMapFiles​
            (java.lang.String rootSrcCodeDirName)
        Deprecated.
        Retrieves all User-Provided HTML Embed-Tag Map Files in his source-directory tree.
        Parameters:
        rootSrcCodeDirName - The root source-directory
        Returns:
        All Externa-HTML <EMBED> Tag-to-FileName map files.
        See Also:
        FileNode, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         return FileNode
     .createRoot(rootSrcCodeDirName)
     .loadTree(
         -1,
         (File dir, String fName) -> fName.equals("external-html-ids.properties"),
         null
     )
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);

      • 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>.
        See Also:
        HTML_FILE_FILTER, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         if (! (new File(rootJDOutDirName + "src-html" + File.separator)).exists())
     return Stream.empty();

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

        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>.
        See Also:
        HTML_FILE_FILTER, DIRS_TO_SKIP, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM)
     .filter((String fileName) ->
         fileName.contains("package-summary.html")   ||
         fileName.contains("package-tree.html")      ||
         fileName.contains("package-frame.html")
     );

      • getFrameSummaryHTMLFiles

        🡅  🡇  ⇈  ⮫ 
        public static java.util.stream.Stream<java.lang.String> getFrameSummaryHTMLFiles​
            (java.lang.String rootJDOutDirName)
        This method retrieves all package-frame.html and package-summary.html 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
        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>.
        See Also:
        HTML_FILE_FILTER, DIRS_TO_SKIP, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
     .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM)
     .filter((String fileName) ->
         fileName.contains("package-summary.html")   ||
         fileName.contains("package-frame.html")
     );

      • 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>.
        See Also:
        HTML_FILE_FILTER, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         return FileNode
     .createRoot(rootJDOutDirName)
     // The 'doc-files/' are user-generated, skip those...
     .loadTree(-1, HTML_FILE_FILTER, (File dir) ->
             (! dir.getName().equals("doc-files"))
         &&  (! dir.getName().equals("hilite-files"))
     )
     .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>.
        See Also:
        getJavaPackageHTMLFiles(String)
        Code:
        Exact Method Body:
         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>.
        See Also:
        getJavaPackageHTMLFiles(String)
        Code:
        Exact Method Body:
         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>.
        See Also:
        HTML_FILE_FILTER, FileNode.flattenJustFiles(VarList), FileNode.RetTypeChoice.FULLPATH_STREAM
        Code:
        Exact Method Body:
         return FileNode
     .createRoot(rootJDOutDirName)
     .loadTree(0, 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>.
        See Also:
        getJavaPackageHTMLFiles(String)
        Code:
        Exact Method Body:
         return JDFiles
     .getJavaPackageHTMLFiles(rootJDOutDirName)
     .filter((String fileName) -> fileName.contains("package-tree.html"));