001package Torello.HTML.Tools.JavaDoc;
002
003import Torello.HTML.HTMLNode;
004import Torello.Java.*;
005
006import Torello.Java.FileNode.RetTypeChoice;
007import Torello.Java.Additional.VarList; // for javadoc
008
009import java.util.*;
010import java.io.*;
011
012import java.util.stream.Stream;
013
014/**
015 * Retrieve Java Doc HTML Files from the Java Doc output directory.
016 * 
017 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID=JDFILES>
018 */
019@StaticFunctional
020public class JDFiles
021{
022    private JDFiles() { }
023
024    /** A Java {@code Predicate} that filters for {@code '.html'} files. */
025    public static final FilenameFilter HTML_FILE_FILTER =
026        (File dir, String name) -> name.trim().endsWith(".html");
027
028    /** A Java {@code Predicate} that avoids directories that contain extranneous files. */
029    public static final FileFilter DIRS_TO_SKIP = (File dir) -> StrCmpr.equalsNAND
030        (dir.getName(), "src-html", "index-files", "doc-files", "hilite-files" );
031
032    /**
033     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GJCHF>
034     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
035     * @return This will return the list of files as a Java {@code Stream<String>}.
036     * @see #HTML_FILE_FILTER
037     * @see #DIRS_TO_SKIP
038     * @see FileNode
039     * @see FileNode#flattenJustFiles(VarList)
040     */
041    public static Stream<String> getJavaClassHTMLFiles(String rootJDOutDirName)
042    {
043        return FileNode
044            .createRoot(rootJDOutDirName)
045            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
046            .prune((FileNode fn) -> StrCmpr.equalsNAND
047                (fn.name, "package-summary.html", "package-tree.html", "package-frame.html"),
048                true
049            )
050            // This 'prune' eliminates HTML files in the *ROOT* Java-Doc directory
051            .prune((FileNode fn) -> ! rootJDOutDirName.equals(fn.getParentPathName()),
052                true
053            )
054            .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);
055
056            /*
057            NOT-OPTIMIZED, WORKS-THOUGH
058            .filter((String fileName) -> StrCmpr.containsNAND(fileName, "package-summary.html", "package-tree.html", "package-frame.html"))
059            .filter((String fileName) -> (StringParse.countCharacters(fileName, File.separator.charAt(0)) > 1));
060                // The previous filter prevents any ".html" files that are in the root java-doc output directory,
061                // ... and are not inside one of the packages.  If a class 'does not have a package' it will be skipped.
062            */
063    }
064
065    /**
066     * This method returns the exact same files as {@link #getJavaClassHTMLFiles(String)}, but
067     * each file returned <I>has been sorted into a specific 'bucket' based on which <B>Java
068     * Package</B> the CIET (class, inteface, enumerated-type, record etc...) HTML file
069     * belongs.</I>
070     * 
071     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
072     * 
073     * @return This will return the list of files, sorted by 'Package Name' - where the package
074     * is merely determined by the directory-name where the file was found.
075     * 
076     * <BR /><TABLE CLASS=BRIEFTABLE>
077     * <TR><TH>Element</TH><TH>Contents</TH></TR>
078     * <TR> <TD>{@code TreeMap} 'key'</TD>
079     *      <TD>The <I>directory-name</I> of the Java-Doc HTML-Directory containing the CIET Java
080     *          Doc HTML Files for a specific package.  (NOTE: This is different than the actual
081     *          'Package Name')
082     *      </TD>
083     *      </TR>
084     * <TR> <TD>{@code TreeMap} 'value'</TD>
085     *      <TD>A {@code Vector} of file-name's (each as a {@code String}) of each Java Doc
086     *          generated HTML file for a CIET in the specific package.
087     *      </TD>
088     *      </TR>
089     * </TABLE>
090     * 
091     * @see #HTML_FILE_FILTER
092     * @see #DIRS_TO_SKIP
093     * @see FileNode
094     * @see FileNode#getParentPathName()
095     * @see FileNode#flattenJustFiles(VarList)
096     */
097    public static TreeMap<String, Vector<String>>
098        getJavaClassHTMLFilesByPackage(String rootJDOutDirName)
099    {
100        TreeMap<String, Vector<String>> ret = new TreeMap<>();
101
102        FileNode
103            .createRoot(rootJDOutDirName)
104            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
105            .flattenJustFiles(RetTypeChoice.STREAM)
106            .filter((FileNode fn) -> StrCmpr.equalsNAND
107                (fn.name, "package-summary.html", "package-tree.html", "package-frame.html"))
108
109            // This 'prune' eliminates HTML files in the *ROOT* Java-Doc directory
110            .filter((FileNode fn) -> ! rootJDOutDirName.equals(fn.getParentPathName()))
111
112            .forEach((FileNode jdHTMLFile) ->
113            {
114                String          packageDirectory    = jdHTMLFile.getParentPathName();
115                Vector<String>  packageFilesList    = ret.get(packageDirectory);
116
117                if (packageFilesList == null)
118                    ret.put(packageDirectory, packageFilesList = new Vector<>());
119
120                packageFilesList.add(jdHTMLFile.name);
121            });
122
123        return ret;
124    }
125
126    /**
127     * Retrieves all User-Provided HTML Embed-Tag Map Files in his source-directory tree.
128     * 
129     * @param rootSrcCodeDirName The root source-directory
130     * @return All Externa-HTML {@code <EMBED>} Tag-to-FileName map files.
131     * @see FileNode
132     * @see FileNode#flattenJustFiles(VarList)
133     */
134    @Deprecated
135    public static Stream<String> allLocalEmbedTagMapFiles(String rootSrcCodeDirName)
136    {
137        return FileNode
138            .createRoot(rootSrcCodeDirName)
139            .loadTree(
140                -1,
141                (File dir, String fName) -> fName.equals("external-html-ids.properties"),
142                null
143            )
144            .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);
145    }
146
147    /**
148     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GSAHF>
149     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
150     * @return This will return the list of files as a Java {@code Stream<String>}.
151     */
152    public static Stream<String> getSrcAsHTMLFiles(String rootJDOutDirName)
153    {
154        if (! (new File(rootJDOutDirName + "src-html" + File.separator)).exists())
155            return Stream.empty();
156
157        return FileNode
158            .createRoot(rootJDOutDirName + "src-html" + File.separator)
159            .loadTree(-1, HTML_FILE_FILTER, null)
160            .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);
161    }
162
163    /**
164     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GJPHF>
165     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
166     * @return This will return the list of files as a Java {@code Stream<String>}.
167     * @see FileNode
168     * @see FileNode#flattenJustFiles(VarList)
169     * @see RetTypeChoice
170     */
171    public static Stream<String> getJavaPackageHTMLFiles(String rootJDOutDirName)
172    {
173        return FileNode
174            .createRoot(rootJDOutDirName)
175            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
176            .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM)
177            .filter((String fileName) ->
178                fileName.contains("package-summary.html")   ||
179                fileName.contains("package-tree.html")      ||
180                fileName.contains("package-frame.html")
181            );
182    }
183
184    /**
185     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_FRAMESUMM>
186     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
187     * @return This will return the list of files as a Java {@code Stream<String>}.
188     * @see FileNode
189     * @see FileNode#flattenJustFiles(VarList)
190     * @see RetTypeChoice
191     */
192    public static Stream<String> getFrameSummaryHTMLFiles(String rootJDOutDirName)
193    {
194        return FileNode
195            .createRoot(rootJDOutDirName)
196            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
197            .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM)
198            .filter((String fileName) ->
199                fileName.contains("package-summary.html")   ||
200                fileName.contains("package-frame.html")
201            );
202    }
203
204    /**
205     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GAHF>
206     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
207     * @return This will return the list of files as a Java {@code Stream<String>}.
208     * @see FileNode
209     */
210    public static Stream<String> getAllHTMLFiles(String rootJDOutDirName)
211    {
212        return FileNode
213            .createRoot(rootJDOutDirName)
214            // The 'doc-files/' are user-generated, skip those...
215            .loadTree(-1, HTML_FILE_FILTER, (File dir) ->
216                    (! dir.getName().equals("doc-files"))
217                &&  (! dir.getName().equals("hilite-files"))
218            )
219            .flattenJustFiles(RetTypeChoice.FULLPATH_STREAM);
220    }
221
222    /**
223     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GPSHF>
224     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
225     * @return This will return the list of files as a Java {@code Stream<String>}.
226     * @see #getJavaPackageHTMLFiles(String)
227     */
228    public static Stream<String> getPackageSummaryHTMLFiles(String rootJDOutDirName)
229    {
230        return JDFiles
231            .getJavaPackageHTMLFiles(rootJDOutDirName)
232            .filter((String fileName) -> fileName.contains("package-summary.html"));
233    }
234
235    /**
236     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GPFHF>
237     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
238     * @return This will return the list of files as a Java {@code Stream<String>}.
239     * @see #getJavaPackageHTMLFiles(String)
240     */
241    public static Stream<String> getPackageFrameHTMLFiles(String rootJDOutDirName)
242    {
243        return JDFiles
244            .getJavaPackageHTMLFiles(rootJDOutDirName)
245            .filter((String fileName) -> fileName.contains("package-frame.html"));
246    }
247
248    /**
249     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GHFIR>
250     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
251     * @return This will return the list of files as a Java {@code Stream<String>}.
252     * @see FileNode
253     * @see FileNode#flattenJustFiles(VarList)
254     * @see RetTypeChoice
255     */
256    public static Stream<String> getHTMLFilesInRoot(String rootJDOutDirName)
257    {
258        return FileNode
259            .createRoot(rootJDOutDirName)
260            .loadTree(0, HTML_FILE_FILTER, null)
261            .flattenJustFiles(FileNode.RetTypeChoice.FULLPATH_STREAM);
262    }
263
264    /**
265     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GPTHF>
266     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
267     * @return This will return the list of files as a Java {@code Stream<String>}.
268     * @see #getJavaPackageHTMLFiles(String)
269     */
270    public static Stream<String> getPackageTreeHTMLFiles(String rootJDOutDirName)
271    {
272        return JDFiles
273            .getJavaPackageHTMLFiles(rootJDOutDirName)
274            .filter((String fileName) -> fileName.contains("package-tree.html"));
275    }
276}