001package Torello.HTML.Tools.JavaDoc;
002
003import Torello.HTML.*;
004import Torello.HTML.NodeSearch.*;
005
006import java.util.*;
007
008/**
009 * <B STYLE='color:darkred;'>Java Doc HTML-File Reader:</B>
010 * 
011 * Find and retrieve any of the parts of Java Doc Package-Summary HTML-File.
012 * 
013 * <BR /><BR />
014 * <EMBED CLASS="external-html" DATA-FILE-ID="JDPSUMMARY">
015 */
016@StaticFunctional
017public class PackageSummary
018{
019    private PackageSummary() { }
020
021    /**
022     * This returns an {@code Iterator} for all of the table-rows in a "Package Summary" 
023     * web-page generated by Java-Doc.
024     * 
025     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
026     * 
027     * @return Iterates all entires in all tables of this package-summary.
028     * 
029     * @throws IllegalArgumentException
030     */
031    public static HNLIInclusive iterator(Vector<HTMLNode> fileVec)
032    {
033        DotPair main = listAll(fileVec);
034
035        if (main == null) throw new IllegalArgumentException(
036            "The HTML Vector provided to parameter 'fileVec' did not have a " +
037            "<UL CLASS='blockList'> element.  fileVec.size(): [" + fileVec.size() + "], " +
038            "has " + TagNodeCount.all(fileVec, TC.OpeningTags, "ul") + " total <UL> element(s)."
039        );
040
041        HNLIInclusive iter = InnerTagInclusiveIterator.get
042            (fileVec, "tr", "class", TextComparitor.C_OR, "rowColor", "altColor");
043
044        iter.restrictCursor(main);
045
046        return iter;
047    }
048
049    /**
050     * Retrieves a list of all CIET Names in a Java Doc {@code 'package-summary.html'} page.  This
051     * is, essentialy, all of the <B>DOCUMENTED</B> Types / CIET's in a given Java Package.  The
052     * {@code String's} are saved into the provided {@code TreeSet<String>} parameter, and <I>these
053     * names only include class-name itself, without the full-package name being appended.</I>
054     * 
055     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
056     * 
057     * @param packageCIETList This should be a reference to an empty {@code TreeSet<String>}.  This
058     * reference will be filled with all the Type-Names (CIET-Names) listed on this Package Summary
059     * Page.
060     */
061    public static void fillCIETList(Vector<HTMLNode> fileVec, TreeSet<String> packageCIETList)
062    {
063        // Iterates the <TR>'s (Table-Row HTML Inclusive Iterator) - IN ALL TABLES of the input
064        // 'package-summary.html' file.  This method is defined above, in this class.
065
066        HNLIInclusive iter = PackageSummary.iterator(fileVec);
067
068        while (iter.hasNext())
069        {
070            Vector<HTMLNode>    cieteeVec   = iter.next();
071            int                 pos         = TagNodeFind.first(cieteeVec, TC.OpeningTags, "a");
072
073            // Simply add it to the TreeSet
074            packageCIETList.add(cieteeVec.elementAt(pos + 1).str);
075        }
076    }
077
078    /**
079     * Retrieves the primary surrounding {@code <UL>} element that lists of all of the
080     * entites (classes, interfaces, etc...) that are contained by the package provided to this
081     * method.
082     * 
083     * <DIV CLASS=HTML>{@code
084     * <ul class="blockList">
085     *   <li class="blockList">
086     *   <!-- Contains 'Type Summary' HTML Tables -->
087     * }</DIV>
088     * 
089     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
090     * 
091     * @return The complete-list of all classes, interfaces, enums, errors, exceptions and 
092     * annotations - <I>as an instance of {@code DotPair}</I>
093     */
094    public static DotPair listAll(Vector<HTMLNode> fileVec)
095    {
096        return InnerTagFindInclusive.first
097            (fileVec, "ul", "class", TextComparitor.C, "blockList");
098    }
099
100    /**
101     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
102     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
103     * {@code Interface Summary}.
104     * 
105     * <DIV CLASS=HTML>{@code
106     * <li class="blockList">
107     *  <table class="typeSummary">
108     *  <caption><span>Interface Summary</span><span class="tabEnd">&nbsp;</span></caption>
109     *  <tr>
110     * ...
111     * }</DIV>
112     * 
113     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
114     * 
115     * @return The "Interface Summary" section of the "Package Summary", or null if the
116     * package-summary page provided did not have an "Interface Summary" section
117     */
118    public static DotPair interfaces(Vector<HTMLNode> fileVec)
119    { return typeSummary(fileVec, "Interface Summary"); }
120
121    /**
122     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
123     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
124     * {@code Class Summary}.
125     * 
126     * <DIV CLASS=HTML>{@code
127     * <li class="blockList">
128     *  <table class="typeSummary">
129     *  <caption><span>Class Summary</span><span class="tabEnd">&nbsp;</span></caption>
130     *  <tr>
131     * ...
132     * }</DIV>
133     * 
134     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
135     * 
136     * @return The "Class Summary" section of the "Package Summary", or null if the
137     * package-summary page provided did not have an "Class Summary" section
138     */
139    public static DotPair classes(Vector<HTMLNode> fileVec)
140    { return typeSummary(fileVec, "Class Summary"); }
141
142    /**
143     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
144     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
145     * {@code Enum Summary}.
146     * 
147     * <DIV CLASS=HTML>{@code
148     * <li class="blockList">
149     *  <table class="typeSummary">
150     *  <caption><span>Enum Summary</span><span class="tabEnd">&nbsp;</span></caption>
151     *  <tr>
152     * ...
153     * }</DIV>
154     * 
155     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
156     * 
157     * @return The "Enum Summary" section of the "Package Summary", or null if the package-summary
158     * page provided did not have an "Enum Summary" section
159     */
160    public static DotPair enums(Vector<HTMLNode> fileVec)
161    { return typeSummary(fileVec, "Enum Summary"); }
162
163    /**
164     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
165     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
166     * {@code Exception Summary}.
167     * 
168     * <DIV CLASS=HTML>{@code
169     * <li class="blockList">
170     *  <table class="typeSummary">
171     *  <caption><span>Exception Summary</span><span class="tabEnd">&nbsp;</span></caption>
172     *  <tr>
173     * ...
174     * }</DIV>
175     * 
176     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
177     * 
178     * @return The "Exception Summary" section of the "Package Summary", or null if the
179     * package-summary page provided did not have an "Exception Summary" section
180     */
181    public static DotPair exceptions(Vector<HTMLNode> fileVec)
182    { return typeSummary(fileVec, "Exception Summary"); }
183
184    /**
185     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
186     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
187     * {@code Error Summary}.
188     * 
189     * <DIV CLASS=HTML>{@code
190     * <li class="blockList">
191     *  <table class="typeSummary">
192     *  <caption><span>Error Summary</span><span class="tabEnd">&nbsp;</span></caption>
193     *  <tr>
194     * ...
195     * }</DIV>
196     * 
197     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
198     * 
199     * @return The "Error Summary" section of the "Package Summary", or null if the
200     * package-summary page provided did not have an "Error Summary" section
201     */
202    public static DotPair errors(Vector<HTMLNode> fileVec)
203    { return typeSummary(fileVec, "Error Summary"); }
204
205    /**
206     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
207     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
208     * {@code Annotation Types Summary}.
209     * 
210     * <DIV CLASS=HTML>{@code
211     * <li class="blockList">
212     *  <table class="typeSummary">
213     *  <caption><span>Annotation Types Summary</span><span class="tabEnd">&nbsp;</span></caption>
214     *  <tr>
215     * ...
216     * }</DIV>
217     * 
218     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
219     * 
220     * @return The "Annotation Types Summary" section of the "Package Summary", or null if the
221     * package-summary page provided did not have an "Error Summary" section
222     */
223    public static DotPair annotations(Vector<HTMLNode> fileVec)
224    { return typeSummary(fileVec, "Annotation Types Summary"); }
225
226    private static DotPair typeSummary(Vector<HTMLNode> fileVec, String type)
227    {
228        HNLIInclusive iter = InnerTagInclusiveIterator.get
229            (fileVec, "table", "class", TextComparitor.C, "typeSummary");
230
231        while (iter.hasNext())
232        {
233            DotPair     table   = iter.nextDotPair();
234            DotPair     dp      = TagNodeFindInclusive.first(fileVec, table.start, table.end, "caption");
235            HTMLNode    n;
236
237            for (int pos = dp.start; pos < dp.end; pos++)
238                if ((n = fileVec.elementAt(pos)).isTextNode())
239                    if (n.str.equals(type))
240                        return table;
241        }
242
243        return null;
244    }
245}