001package Torello.JavaDoc;
002
003import Torello.Java.*;
004
005import Torello.HTML.HTMLNode;
006
007import Torello.Java.ReadOnly.ReadOnlyList;
008import Torello.Java.ReadOnly.ROTreeMapBuilder;
009import Torello.Java.ReadOnly.ReadOnlyMap;
010
011
012import java.util.*;
013import java.io.*;
014
015import java.util.stream.Stream;
016
017/**
018 * Retrieve Java Doc HTML Files from the Java Doc output directory.
019 * 
020 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=JDFILES>
021 */
022@StaticFunctional
023public class JDFiles
024{
025    private JDFiles() { }
026
027    /** A Java {@code Predicate} that filters for {@code '.html'} files. */
028    public static final FilenameFilter HTML_FILE_FILTER =
029        (File dir, String name) -> name.trim().endsWith(".html");
030
031    /** A Java {@code Predicate} that avoids directories that contain extranneous files. */
032    public static final FileFilter DIRS_TO_SKIP = (File dir) -> StrCmpr.equalsNAND
033        (dir.getName(), "src-html", "index-files", "doc-files", "hilite-files" );
034
035    /**
036     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GJCHF>
037     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
038     * @return This will return the list of files as a Java {@code Stream<String>}.
039     * @see #HTML_FILE_FILTER
040     * @see #DIRS_TO_SKIP
041     * @see FileNode
042     * @see FileNode#flattenJustFiles(RTC)
043     * @see RTC#FULLPATH_STREAM()
044     */
045    public static Stream<String> getJavaClassHTMLFiles(String rootJDOutDirName)
046    {
047        return FileNode
048            .createRoot(rootJDOutDirName)
049            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
050            .prune(
051                (FileNode fn) -> StrCmpr.equalsNAND
052                    (fn.name, "package-summary.html", "package-tree.html", "package-frame.html"),
053                true
054            )
055            // This 'prune' eliminates HTML files in the *ROOT* Java-Doc directory
056            .prune(
057                (FileNode fn) -> ! rootJDOutDirName.equals(fn.getParentPathName()),
058                true
059            )
060            .flattenJustFiles(RTC.FULLPATH_STREAM());
061    }
062
063    /**
064     * This method returns the exact same files as {@link #getJavaClassHTMLFiles(String)}, but
065     * each file returned <I>has been sorted into a specific 'bucket' based on which <B>Java
066     * Package</B> the CIET (class, inteface, enumerated-type, record etc...) HTML file
067     * belongs.</I>
068     * 
069     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
070     * 
071     * @return This will return the list of files, sorted by 'Package Name' - where the package
072     * is merely determined by the directory-name where the file was found.
073     * 
074     * <BR /><TABLE CLASS=JDBriefTable>
075     * 
076     * <TR><TH>Element</TH><TH>Contents</TH></TR>
077     * 
078     * <TR> <TD>{@code ReadOnlyMap} '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></TR>
083     * 
084     * <TR> <TD>{@code ReadOnlyMap} 'value'</TD>
085     *      <TD>A {@code ReadOnlyList} 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></TR>
088     * 
089     * </TABLE>
090     * 
091     * @see #HTML_FILE_FILTER
092     * @see #DIRS_TO_SKIP
093     * @see FileNode
094     * @see FileNode#getParentPathName()
095     * @see FileNode#flattenJustDirs()
096     */
097    public static ReadOnlyMap<String, ReadOnlyList<String>>
098        getJavaClassHTMLFilesByPackage(String rootJDOutDirName)
099    {
100        // TreeMap<String, Vector<String>> ret = new TreeMap<>();
101        ROTreeMapBuilder<String, ReadOnlyList<String>> b = new ROTreeMapBuilder<>();
102
103        // These are files usually found in a Package-Directory.  These cannot be processed by
104        // the class "MainFilesProcessor".  These files are not for CIET/Types (specific class
105        // JD Files), but rather if/when these files need to be modified they are handled by the
106        // "ExtraFilesProcessor"
107
108        FileNodeFilter TYPE_HTML_FILES = (FileNode fn) -> StrCmpr.equalsNAND
109            (fn.name, "package-summary.html", "package-tree.html", "package-frame.html");
110
111        FileNode
112            .createRoot(rootJDOutDirName)
113            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
114            .flattenJustDirs()
115            .forEach((FileNode packageDirFN) ->
116            {
117                // The Full-Path Directory name of a single Java Package
118                String packageDir = packageDirFN.getFullPathName();
119
120                // The root 'javadoc/' directory doesn't have any of the Java class files
121                if (packageDir.equals(rootJDOutDirName)) return;
122
123                // Retrieve all CIET/Type Web-Pages for a single package-directory
124                ReadOnlyList<String> cietFileNames = packageDirFN.getDirContentsFiles
125                    (RTC.SORTED_FILENAME_ROAL(), TYPE_HTML_FILES);
126
127                // Sometimes a Java-Package doesn't have any files in it.  Skip those dirs.
128                if (cietFileNames.size() > 0) b.put(packageDir, cietFileNames);
129            });
130
131        return b.build();
132    }
133
134    /*
135    // NOTE: The original way of doing this was kind of stupid (but it did work!)
136    FileNode
137        .createRoot(rootJDOutDirName)
138        .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
139        .flattenJustFiles(RetTypeChoice.STREAM)
140        .filter(
141            (FileNode fn) -> StrCmpr.equalsNAND
142                (fn.name, "package-summary.html", "package-tree.html", "package-frame.html"))
143
144        // This 'prune' eliminates HTML files in the *ROOT* Java-Doc directory
145        .filter((FileNode fn) -> ! rootJDOutDirName.equals(fn.getParentPathName()))
146
147        .forEach((FileNode jdHTMLFile) ->
148        {
149            String          packageDirectory    = jdHTMLFile.getParentPathName();
150            Vector<String>  packageFilesList    = ret.get(packageDirectory);
151
152            if (packageFilesList == null)
153                ret.put(packageDirectory, packageFilesList = new Vector<>());
154
155            packageFilesList.add(jdHTMLFile.name);
156        });
157
158    return ret;
159    */
160
161
162    /**
163     * Retrieves all User-Provided HTML Embed-Tag Map Files in his source-directory tree.
164     * 
165     * @param rootSrcCodeDirName The root source-directory
166     * @return All Externa-HTML {@code <EMBED>} Tag-to-FileName map files.
167     * @see FileNode
168     * @see FileNode#flattenJustFiles(RTC)
169     * @see RTC#FULLPATH_STREAM()
170     */
171    @Deprecated
172    public static Stream<String> allLocalEmbedTagMapFiles(String rootSrcCodeDirName)
173    {
174        return FileNode
175            .createRoot(rootSrcCodeDirName)
176            .loadTree(
177                -1,
178                (File dir, String fName) -> fName.equals("external-html-ids.properties"),
179                null
180            )
181            .flattenJustFiles(RTC.FULLPATH_STREAM());
182    }
183
184    /**
185     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GSAHF>
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 #HTML_FILE_FILTER
189     * @see FileNode#flattenJustFiles(RTC)
190     * @see RTC#FULLPATH_STREAM()
191     */
192    public static Stream<String> getSrcAsHTMLFiles(String rootJDOutDirName)
193    {
194        if (! (new File(rootJDOutDirName + "src-html" + File.separator)).exists())
195            return Stream.empty();
196
197        return FileNode
198            .createRoot(rootJDOutDirName + "src-html" + File.separator)
199            .loadTree(-1, HTML_FILE_FILTER, null)
200            .flattenJustFiles(RTC.FULLPATH_STREAM());
201    }
202
203    /**
204     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GJPHF>
205     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
206     * @return This will return the list of files as a Java {@code Stream<String>}.
207     * @see #HTML_FILE_FILTER
208     * @see #DIRS_TO_SKIP
209     * @see FileNode#flattenJustFiles(RTC)
210     * @see RTC#FULLPATH_STREAM()
211     */
212    public static Stream<String> getJavaPackageHTMLFiles(String rootJDOutDirName)
213    {
214        return FileNode
215            .createRoot(rootJDOutDirName)
216            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
217            .flattenJustFiles(RTC.FULLPATH_STREAM())
218            .filter((String fileName) ->
219                fileName.endsWith("package-summary.html")   ||
220                fileName.endsWith("package-tree.html")      ||
221                fileName.endsWith("package-frame.html")
222            );
223    }
224
225    /**
226     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_FRAMESUMM>
227     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
228     * @return This will return the list of files as a Java {@code Stream<String>}.
229     * @see #HTML_FILE_FILTER
230     * @see #DIRS_TO_SKIP
231     * @see FileNode#flattenJustFiles(RTC)
232     * @see RTC#FULLPATH_STREAM()
233     */
234    public static Stream<String> getFrameSummaryHTMLFiles(String rootJDOutDirName)
235    {
236        return FileNode
237            .createRoot(rootJDOutDirName)
238            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
239            .flattenJustFiles(RTC.FULLPATH_STREAM())
240            .filter((String fileName) ->
241                fileName.endsWith("package-summary.html")   ||
242                fileName.endsWith("package-frame.html")
243            );
244    }
245
246    /**
247     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GAHF>
248     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
249     * @return This will return the list of files as a Java {@code Stream<String>}.
250     * @see #HTML_FILE_FILTER
251     * @see FileNode#flattenJustFiles(RTC)
252     * @see RTC#FULLPATH_STREAM()
253     */
254    public static Stream<String> getAllHTMLFiles(String rootJDOutDirName)
255    {
256        return FileNode
257            .createRoot(rootJDOutDirName)
258            // The 'doc-files/' are user-generated, skip those...
259            .loadTree(-1, HTML_FILE_FILTER, (File dir) ->
260                    (! dir.getName().equals("doc-files"))
261                &&  (! dir.getName().equals("hilite-files"))
262            )
263            .flattenJustFiles(RTC.FULLPATH_STREAM());
264    }
265
266    /**
267     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GPSHF>
268     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
269     * @return This will return the list of files as a Java {@code Stream<String>}.
270     */
271    public static Stream<String> getPackageSummaryHTMLFiles(String rootJDOutDirName)
272    {
273        return FileNode
274            .createRoot(rootJDOutDirName)
275            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
276            .flattenJustFiles(RTC.FULLPATH_STREAM())
277            .filter((String fileName) -> fileName.endsWith("package-summary.html"));
278    }
279
280    /**
281     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GPFHF>
282     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
283     * @return This will return the list of files as a Java {@code Stream<String>}.
284     */
285    public static Stream<String> getPackageFrameHTMLFiles(String rootJDOutDirName)
286    {
287        return FileNode
288            .createRoot(rootJDOutDirName)
289            .loadTree(-1, HTML_FILE_FILTER, DIRS_TO_SKIP)
290            .flattenJustFiles(RTC.FULLPATH_STREAM())
291            .filter((String fileName) -> fileName.endsWith("package-frame.html"));
292    }
293
294    /**
295     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GHFIR>
296     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
297     * @return This will return the list of files as a Java {@code Stream<String>}.
298     * @see #HTML_FILE_FILTER
299     * @see FileNode#flattenJustFiles(RTC)
300     * @see RTC#FULLPATH_STREAM()
301     */
302    public static Stream<String> getHTMLFilesInRoot(String rootJDOutDirName)
303    {
304        return FileNode
305            .createRoot(rootJDOutDirName)
306            .loadTree(0, HTML_FILE_FILTER, null)
307            .flattenJustFiles(RTC.FULLPATH_STREAM());
308    }
309
310    /**
311     * <EMBED CLASS='external-html' DATA-FILE-ID=JDF_GPTHF>
312     * @param rootJDOutDirName <EMBED CLASS='external-html' DATA-FILE-ID=JDF_ROOT>
313     * @return This will return the list of files as a Java {@code Stream<String>}.
314     * @see #getJavaPackageHTMLFiles(String)
315     */
316    public static Stream<String> getPackageTreeHTMLFiles(String rootJDOutDirName)
317    {
318        return JDFiles
319            .getJavaPackageHTMLFiles(rootJDOutDirName)
320            .filter((String fileName) -> fileName.contains("package-tree.html"));
321    }
322}