001package Torello.HTML.Tools.JavaDoc;
002
003import Torello.HTML.*;
004import Torello.HTML.NodeSearch.*;
005
006import java.util.*;
007import java.io.*;
008
009/**
010 * <CODE>Details Class Documentation.</CODE><BR /><BR />
011 * <EMBED CLASS="external-html" DATA-FILE-ID="DETMAINDESC">
012 */
013@StaticFunctional
014public class Details
015{
016    private Details() { }
017
018    /**
019     * When a {@code JavaDocError} is thrown looking for a <B>Details Section,</B> this message
020     * shall be produced.  JavaDoc will always produce a details section - however there have been
021     * (some, not many) situations where the output HTML was not properly formatted.  This can be
022     * remedied, but it is advisable to inspect what has caused the problem, and repair the HTML
023     * first.
024     *
025     * <BR /><BR /><B>NOTE:</B> This particular error message is used only when the
026     * {@code CommentNode} that looks like below is missing:
027     * <BR />{@code '========= FIELD DETAIL =========='}
028     *
029     * <BR /><BR /><B><SPAN STYLE="color: red;">NOTE: </B></SPAN>
030     * 
031     * <BR /><BR /><UL CLASS="JDUL">
032     * <LI> {@code TOK1} will be replaced by the word: {@code Field, Constructor} or
033     *      {@code Method}.
034     *      <BR /><BR />
035     * </LI>
036     * <LI> {@code TOK2} will be replaced by the word: {@code FIELD, CONSTRUCTOR} or
037     *      {@code METHOD}.
038     *      <BR />
039     * </LI>
040     * </UL>
041     */
042    protected static final String errorMsg1 =
043        "Could not find a TOK1 Details Section in this JavaDoc Page.  " +
044        "Returned DotPair would be null.  JavaDoc Class HTML Page did not have " +
045        "a CommentNode whose body contained sub-string '======= TOK2 DETAIL ======='.  " +
046        "Java Error.";
047
048    /**
049     * When a {@code JavaDocError} is thrown looking for a <B>Details Section,</B> this message
050     * shall be produced. JavaDoc will always produce a details section - however there have been
051     * (some, not many) situations where the output HTML was not properly formatted.  This can be
052     * remedied, but it is advisable to inspect what has caused the problem, and repair the HTML
053     * first.  There are also occasions when a class does not have have {@code Field's}, or
054     * {@code Constructor's} - or possibly even {@code Method's.}
055     *
056     * <BR /><BR /><B>NOTE:</B> This particular error message is used only when the following
057     * Unordered list seems to be missing.  This should not happen, but this is used with an
058     * instance of the {@code 'Error' Throwable.}
059     *
060     * <BR /><BR /><B><SPAN STYLE="color: red;">NOTE: </B></SPAN>
061     * {@code TOK} will be replaced by the word: {@code Field, Constructor} or {@code Method}.
062     */
063    protected static final String errorMsg2 =
064        "Could not find a TOK Details Section in this JavaDoc Page.  " +
065        "Returned DotPair would be null.  JavaDoc Class HTML Page did not have " +
066        "a TagNode of HTML Element type <UL class='blockNode'>.  Java Error.";
067
068    /**
069     * When a {@code JavaDocError} is thrown looking for the "sublist {@code <UL>...</UL>} 
070     * <B>Details Section,</B> this message shall be produced.  JavaDoc will always produce a
071     * details section - however there have been (very few) situations where the output HTML was
072     * not properly formatted.  This can be remedied, but it is advisable to inspect what has
073     * caused the problem, and repair the HTML first.
074     *
075     * <BR /><BR /><B><SPAN STYLE="color: red;">NOTE: </B></SPAN>
076     * {@code TOK} will be replaced by the word: {@code Field, Constructor} or {@code Method}.
077     */
078    protected static final String errorMsg3 = 
079        "Search for TOK Summaries in this JavaDoc Page returned a null-valued Iterator.  " +
080        "Class HNLIInclusive was not instantiated when searching for HTML <UL> Elements having " +
081        "'class' Attributes = 'rowColor' or 'altColor.'  Java Error.";
082
083    // ********************************************************************************************
084    // ********************************************************************************************
085    // Retrieve Details - Entire 'Details' Section
086    // ********************************************************************************************
087    // ********************************************************************************************
088
089    /**
090     * <EMBED CLASS="external-html" DATA-FILE-ID="JDDETMETH">
091     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
092     * @return An instance of {@code class DotPair} that points to the begin and end index
093     * locations of input parameter {@code 'javaDocHTMLCIETPage'} were the primary <B>'Details
094     * Section'</B> resides.
095     * @see Torello.HTML.NodeSearch.AVT
096     * @see Torello.HTML.NodeSearch.InnerTagFindInclusive
097     * @see Torello.HTML.DotPair
098     */
099    public static DotPair details(Vector<HTMLNode> javaDocHTMLCIETPage)
100    {
101        DotPair ret = InnerTagFindInclusive.first
102            (javaDocHTMLCIETPage, "div", "class", TextComparitor.C, "details");
103
104        if (ret == null) throw new JavaDocError
105            ("Could not find an HTML Divider Element whose class attribute was class='details'");
106
107        return ret;
108    }
109
110
111    // ********************************************************************************************
112    // ********************************************************************************************
113    // Retrieve Details - Complete Section
114    // ********************************************************************************************
115    // ********************************************************************************************
116
117    /**
118     * <EMBED CLASS="external-html" DATA-FILE-ID="JDCONDET">
119     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
120     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
121     * @see Torello.HTML.NodeSearch.CommentNodeFind
122     * @see Torello.HTML.NodeSearch.InnerTagFindInclusive
123     * @see Torello.HTML.DotPair
124     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
125     */
126    public static DotPair constructorDetails (Vector<HTMLNode> javaDocHTMLCIETPage)
127    {
128        int constructorDetailsPos = CommentNodeFind.first
129            (javaDocHTMLCIETPage, TextComparitor.CN_CI, "== CONSTRUCTOR DETAIL ==");
130
131        if (constructorDetailsPos == -1) throw new JavaDocError(
132            errorMsg1.replace("TOK1", "Constructor").replace("TOK2", "CONSTRUCTOR")
133        );
134
135        DotPair ret = InnerTagFindInclusive.first(
136            javaDocHTMLCIETPage, constructorDetailsPos, -1, "ul", "class",
137            TextComparitor.C, "blockList"
138        );
139
140        if (ret == null) throw new JavaDocError(errorMsg2.replace("TOK", "Constructor"));
141
142        return ret;
143    }
144
145    /**
146     * <EMBED CLASS="external-html" DATA-FILE-ID="JDFDET">
147     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">  
148     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
149     * @see Torello.HTML.NodeSearch.CommentNodeFind
150     * @see Torello.HTML.NodeSearch.InnerTagFindInclusive
151     * @see Torello.HTML.DotPair
152     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
153     */
154    public static final DotPair fieldDetails(Vector<HTMLNode> javaDocHTMLCIETPage)
155    {
156        int fieldDetailsPos = CommentNodeFind.first
157            (javaDocHTMLCIETPage, TextComparitor.CN_CI, "== FIELD DETAIL ==");
158
159        if (fieldDetailsPos == -1) throw new JavaDocError(
160            errorMsg1.replace("TOK1", "Field").replace("TOK2", "FIELD")
161        );
162
163        DotPair ret = InnerTagFindInclusive.first(
164            javaDocHTMLCIETPage, fieldDetailsPos, -1, "ul", "class",
165            TextComparitor.C, "blockList"
166        );
167
168        if (ret == null) throw new JavaDocError(errorMsg2.replace("TOK", "Field"));
169
170        return ret;
171    }
172
173    /**
174     * <EMBED CLASS="external-html" DATA-FILE-ID="JDECDET"> 
175     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
176     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
177     * @see Torello.HTML.NodeSearch.CommentNodeFind
178     * @see Torello.HTML.NodeSearch.InnerTagFindInclusive
179     * @see Torello.HTML.DotPair
180     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
181     */
182    public static final DotPair enumConstDetails(Vector<HTMLNode> javaDocHTMLCIETPage)
183    {
184        int fieldDetailsPos = CommentNodeFind.first
185            (javaDocHTMLCIETPage, TextComparitor.CN_CI, "== ENUM CONSTANT DETAIL ==");
186
187        if (fieldDetailsPos == -1) throw new JavaDocError(
188            errorMsg1.replace("TOK1", "Enumerated-Constant").replace("TOK2", "ENUM CONSTANT")
189        );
190
191        DotPair ret = InnerTagFindInclusive.first(
192            javaDocHTMLCIETPage, fieldDetailsPos, -1, "ul", "class",
193            TextComparitor.C, "blockList"
194        );
195
196        if (ret == null) throw new JavaDocError(errorMsg2.replace("TOK", "Enumerated-Constant"));
197
198        return ret;
199    }
200
201    /**
202     * <EMBED CLASS="external-html" DATA-FILE-ID="JDMETHDET">
203     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
204     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
205     * @see Torello.HTML.NodeSearch.CommentNodeFind
206     * @see Torello.HTML.NodeSearch.InnerTagFindInclusive
207     * @see Torello.HTML.DotPair
208     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
209     */
210    public static DotPair methodDetails (Vector<HTMLNode> javaDocHTMLCIETPage)
211    {
212        int methodDetailsPos = CommentNodeFind.first
213            (javaDocHTMLCIETPage, TextComparitor.CN_CI, "== METHOD DETAIL ==");
214
215        if (methodDetailsPos == -1) throw new JavaDocError(
216            errorMsg1.replace("TOK1", "Method").replace("TOK2", "METHOD")
217        );
218
219        DotPair ret = InnerTagFindInclusive.first(
220            javaDocHTMLCIETPage, methodDetailsPos, -1, "ul", "class",
221            TextComparitor.C, "blockList"
222        );
223
224        if (ret == null) throw new JavaDocError
225            (errorMsg2.replace("TOK", "Method"));
226
227        return ret;
228    }
229
230
231    // ********************************************************************************************
232    // ********************************************************************************************
233    // Retrieve Details - Complete Section, But Won't Throw JavaDocError
234    // ********************************************************************************************
235    // ********************************************************************************************
236
237
238    /**
239     * This method is identical to the method {@code DotPair constructorDetails(...)}, but it
240     * catches the {@code JavaDocError}, and returns null instead.  Both methods are preserved in
241     * this class, because there are, of course, situations where a class does not have a
242     * Constructor Details Section.
243     * 
244     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
245     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
246     * @see #constructorDetails(Vector)
247     */
248    public static DotPair hasConstructorDetails (Vector<HTMLNode> javaDocHTMLCIETPage)
249    {
250        try
251            { return constructorDetails(javaDocHTMLCIETPage); }
252        catch (JavaDocError e)
253            { return null; }
254    }
255
256    /**
257     * This method is identical to the method {@code DotPair fieldDetails(...)}, but it catches
258     * the {@code JavaDocError}, and returns null instead.  Both methods are preserved in this
259     * class, because there are, of course, situations where a class does not have a Field Details
260     * Section.
261     * 
262     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
263     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
264     * @see #fieldDetails(Vector)
265     */
266    public static DotPair hasFieldDetails (Vector<HTMLNode> javaDocHTMLCIETPage)
267    {
268        try
269            { return fieldDetails(javaDocHTMLCIETPage); }
270        catch (JavaDocError e)
271            { return null; }
272    }
273
274
275    /**
276     * This method is identical to the method {@code DotPair enumConstDetails(...)}, but it catches
277     * the {@code JavaDocError}, and returns null instead.  Both methods are preserved in this
278     * class, because there are, of course, situations where a class does not have an Enumerated
279     * Constant Details Section.
280     * 
281     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
282     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
283     * @see #fieldDetails(Vector)
284     */
285    public static DotPair hasEnumConstDetails (Vector<HTMLNode> javaDocHTMLCIETPage)
286    {
287        try
288            { return enumConstDetails(javaDocHTMLCIETPage); }
289        catch (JavaDocError e) 
290            { return null; }
291    }
292
293    /**
294     * This method is identical to the method {@code DotPair methodDetails(...)}, but it catches
295     * the {@code JavaDocError}, and returns null instead.  Both methods are preserved in this
296     * class, because there are, of course, situations where a class does not have a Method Details
297     * Section.
298     * 
299     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
300     * @return <EMBED CLASS='external-html' DATA-FILE-ID=DETAILDPRET>
301     * @see #methodDetails(Vector)
302     */
303    public static DotPair hasMethodDetails (Vector<HTMLNode> javaDocHTMLCIETPage)
304    {
305        try
306            { return methodDetails(javaDocHTMLCIETPage); }
307        catch (JavaDocError e)
308            { return null; }
309    }
310
311
312    // ********************************************************************************************
313    // ********************************************************************************************
314    // Retrieve Summaries - HNLIInclusive Iterators
315    // ********************************************************************************************
316    // ********************************************************************************************
317
318
319    /**
320     * <EMBED CLASS="external-html" DATA-FILE-ID="JDCDITER">
321     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
322     * @return <EMBED class='external-html' DATA-FILE-ID=DETHNLIRET>
323     * <BR /><BR />The {@code <UL>} elements iterated contain {@code Constructor} definitions.
324     * @see Torello.HTML.NodeSearch.InnerTagInclusiveIterator
325     * @see Torello.HTML.NodeSearch.HNLIInclusive
326     * @see #constructorDetails(Vector)
327     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
328     */
329    public static HNLIInclusive constructorDetailsIterator(Vector<HTMLNode> javaDocHTMLCIETPage)
330    {
331        DotPair constructorDetailsSection = constructorDetails(javaDocHTMLCIETPage);
332
333        HNLIInclusive ret = InnerTagInclusiveIterator.get
334            (javaDocHTMLCIETPage, "ul", "class", TextComparitor.C, "blockList", "blockListLast");
335            // <ul class='blockList'> is used for all entries, except the last in the last
336            // <ul class='blockListLast'> is used for last entry.
337
338        if (ret == null) throw new JavaDocError(errorMsg3.replace("TOK", "Constructor"));
339
340        // '+ 1' is needed since there is an "outer <UL class='blockList'>" TagNode
341        // ==>  The "Constructor Details (entire) Section" is 
342        //      also a <UL CLASS='blockList'> too!
343        ret.restrictCursor(constructorDetailsSection.start + 1, constructorDetailsSection.end);
344
345        return ret;
346    }
347
348    /**
349     * <EMBED CLASS="external-html" DATA-FILE-ID="JDFDITER">
350     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
351     * @return <EMBED class='external-html' DATA-FILE-ID=DETHNLIRET>
352     * <BR /><BR />The {@code <UL>} elements iterated contain {@code Field} definitions.
353     * @see Torello.HTML.NodeSearch.InnerTagInclusiveIterator
354     * @see Torello.HTML.NodeSearch.HNLIInclusive
355     * @see #fieldDetails(Vector)
356     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
357     */
358    public static HNLIInclusive fieldDetailsIterator(Vector<HTMLNode> javaDocHTMLCIETPage)
359    {
360        DotPair fieldDetailsSection = fieldDetails(javaDocHTMLCIETPage);
361
362        HNLIInclusive ret = InnerTagInclusiveIterator.get(javaDocHTMLCIETPage,
363            "ul", "class", TextComparitor.C, "blockList", "blockListLast");
364            // <ul class='blockList'> is used for all entries, except the last in the last
365            // <ul class='blockListLast'> is used for last entry.
366
367        if (ret == null) throw new JavaDocError(errorMsg3.replace("TOK", "Field"));
368
369        // '+ 1' is needed since there is an "outer <UL class='blockList'>" TagNode
370        // ==> The "Field Details (entire) Section" is also a <UL CLASS='blockList'> too!
371        ret.restrictCursor(fieldDetailsSection.start + 1, fieldDetailsSection.end);
372
373        return ret;
374    }
375
376    /**
377     * <EMBED CLASS="external-html" DATA-FILE-ID="JDECDITER">
378     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
379     * @return <EMBED class='external-html' DATA-FILE-ID=DETHNLIRET>
380     * <BR /><BR />The {@code <UL>} elements iterated contain {@code Enumerated-Constant}
381     * definitions.
382     * @see Torello.HTML.NodeSearch.InnerTagInclusiveIterator
383     * @see Torello.HTML.NodeSearch.HNLIInclusive
384     * @see #enumConstDetails(Vector)
385     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
386     */
387    public static HNLIInclusive enumConstDetailsIterator(Vector<HTMLNode> javaDocHTMLCIETPage)
388    {
389        DotPair enumConstDetailsSection = enumConstDetails(javaDocHTMLCIETPage);
390
391        HNLIInclusive ret = InnerTagInclusiveIterator.get(javaDocHTMLCIETPage,
392            "ul", "class", TextComparitor.C, "blockList", "blockListLast");
393            // <ul class='blockList'> is used for all entries, except the last in the last
394            // <ul class='blockListLast'> is used for last entry.
395
396        if (ret == null) throw new JavaDocError(errorMsg3.replace("TOK", "Enumerated-Constant"));
397
398        // '+ 1' is needed since there is an "outer <UL class='blockList'>" TagNode
399        // ==>  The "Enumerated-Constant Details (entire) Section" is 
400        //      also a <UL CLASS='blockList'> too!
401        ret.restrictCursor(enumConstDetailsSection.start + 1, enumConstDetailsSection.end);
402
403        return ret;
404    }
405
406    /**
407     * <EMBED CLASS="external-html" DATA-FILE-ID="JDMDITER">
408     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
409     * @return <EMBED class='external-html' DATA-FILE-ID=DETHNLIRET>
410     * <BR /><BR />The {@code <UL>} elements iterated contain {@code Method} definitions.
411     * @see Torello.HTML.NodeSearch.InnerTagInclusiveIterator
412     * @see Torello.HTML.NodeSearch.HNLIInclusive
413     * @see #methodDetails(Vector)
414     * @throws JavaDocError <EMBED CLASS="external-html" DATA-FILE-ID="JDERRUL">
415     */
416    public static HNLIInclusive methodDetailsIterator(Vector<HTMLNode> javaDocHTMLCIETPage)
417    {
418        DotPair methodDetailsSection = methodDetails(javaDocHTMLCIETPage);
419
420        HNLIInclusive ret = InnerTagInclusiveIterator.get(javaDocHTMLCIETPage,
421            "ul", "class", TextComparitor.C, "blockList", "blockListLast");
422            // <ul class='blockList'> is used for all entries, except the last in the last
423            // <ul class='blockListLast'> is used for last entry.
424
425        if (ret == null) throw new JavaDocError(errorMsg3.replace("TOK", "Method"));
426
427        // '+ 1' is needed since there is an "outer <UL class='blockList'>" TagNode
428        // ==> The "Method Details (entire) Section" is also a <UL CLASS='blockList'> too!
429        ret.restrictCursor(methodDetailsSection.start + 1, methodDetailsSection.end);
430
431        return ret;
432    }
433}