1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
package Torello.HTML.Tools.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;

import java.util.*;

/**
 * <B STYLE='color:darkred;'>Java Doc HTML-File Reader:</B>
 * 
 * Find and retrieve any of the parts of Java Doc Package-Summary HTML-File.
 * 
 * <BR /><BR />
 * <EMBED CLASS="external-html" DATA-FILE-ID="JDPSUMMARY">
 */
@StaticFunctional
public class PackageSummary
{
    private PackageSummary() { }

    /**
     * This returns an {@code Iterator} for all of the table-rows in a "Package Summary" 
     * web-page generated by Java-Doc.
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return Iterates all entires in all tables of this package-summary.
     * 
     * @throws IllegalArgumentException
     */
    public static HNLIInclusive iterator(Vector<HTMLNode> fileVec)
    {
        DotPair main = listAll(fileVec);

        if (main == null) throw new IllegalArgumentException(
            "The HTML Vector provided to parameter 'fileVec' did not have a " +
            "<UL CLASS='blockList'> element.  fileVec.size(): [" + fileVec.size() + "], " +
            "has " + TagNodeCount.all(fileVec, TC.OpeningTags, "ul") + " total <UL> element(s)."
        );

        HNLIInclusive iter = InnerTagInclusiveIterator.get
            (fileVec, "tr", "class", TextComparitor.C_OR, "rowColor", "altColor");

        iter.restrictCursor(main);

        return iter;
    }

    /**
     * Retrieves a list of all CIET Names in a Java Doc {@code 'package-summary.html'} page.  This
     * is, essentialy, all of the <B>DOCUMENTED</B> Types / CIET's in a given Java Package.  The
     * {@code String's} are saved into the provided {@code TreeSet<String>} parameter, and <I>these
     * names only include class-name itself, without the full-package name being appended.</I>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @param packageCIETList This should be a reference to an empty {@code TreeSet<String>}.  This
     * reference will be filled with all the Type-Names (CIET-Names) listed on this Package Summary
     * Page.
     */
    public static void fillCIETList(Vector<HTMLNode> fileVec, TreeSet<String> packageCIETList)
    {
        // Iterates the <TR>'s (Table-Row HTML Inclusive Iterator) - IN ALL TABLES of the input
        // 'package-summary.html' file.  This method is defined above, in this class.

        HNLIInclusive iter = PackageSummary.iterator(fileVec);

        while (iter.hasNext())
        {
            Vector<HTMLNode>    cieteeVec   = iter.next();
            int                 pos         = TagNodeFind.first(cieteeVec, TC.OpeningTags, "a");

            // Simply add it to the TreeSet
            packageCIETList.add(cieteeVec.elementAt(pos + 1).str);
        }
    }

    /**
     * Retrieves the primary surrounding {@code <UL>} element that lists of all of the
     * entites (classes, interfaces, etc...) that are contained by the package provided to this
     * method.
     * 
     * <DIV CLASS=HTML>{@code
     * <ul class="blockList">
     *   <li class="blockList">
     *   <!-- Contains 'Type Summary' HTML Tables -->
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The complete-list of all classes, interfaces, enums, errors, exceptions and 
     * annotations - <I>as an instance of {@code DotPair}</I>
     */
    public static DotPair listAll(Vector<HTMLNode> fileVec)
    {
        return InnerTagFindInclusive.first
            (fileVec, "ul", "class", TextComparitor.C, "blockList");
    }

    /**
     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
     * {@code Interface Summary}.
     * 
     * <DIV CLASS=HTML>{@code
     * <li class="blockList">
     *  <table class="typeSummary">
     *  <caption><span>Interface Summary</span><span class="tabEnd">&nbsp;</span></caption>
     *  <tr>
     * ...
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The "Interface Summary" section of the "Package Summary", or null if the
     * package-summary page provided did not have an "Interface Summary" section
     */
    public static DotPair interfaces(Vector<HTMLNode> fileVec)
    { return typeSummary(fileVec, "Interface Summary"); }

    /**
     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
     * {@code Class Summary}.
     * 
     * <DIV CLASS=HTML>{@code
     * <li class="blockList">
     *  <table class="typeSummary">
     *  <caption><span>Class Summary</span><span class="tabEnd">&nbsp;</span></caption>
     *  <tr>
     * ...
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The "Class Summary" section of the "Package Summary", or null if the
     * package-summary page provided did not have an "Class Summary" section
     */
    public static DotPair classes(Vector<HTMLNode> fileVec)
    { return typeSummary(fileVec, "Class Summary"); }

    /**
     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
     * {@code Enum Summary}.
     * 
     * <DIV CLASS=HTML>{@code
     * <li class="blockList">
     *  <table class="typeSummary">
     *  <caption><span>Enum Summary</span><span class="tabEnd">&nbsp;</span></caption>
     *  <tr>
     * ...
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The "Enum Summary" section of the "Package Summary", or null if the package-summary
     * page provided did not have an "Enum Summary" section
     */
    public static DotPair enums(Vector<HTMLNode> fileVec)
    { return typeSummary(fileVec, "Enum Summary"); }

    /**
     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
     * {@code Exception Summary}.
     * 
     * <DIV CLASS=HTML>{@code
     * <li class="blockList">
     *  <table class="typeSummary">
     *  <caption><span>Exception Summary</span><span class="tabEnd">&nbsp;</span></caption>
     *  <tr>
     * ...
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The "Exception Summary" section of the "Package Summary", or null if the
     * package-summary page provided did not have an "Exception Summary" section
     */
    public static DotPair exceptions(Vector<HTMLNode> fileVec)
    { return typeSummary(fileVec, "Exception Summary"); }

    /**
     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
     * {@code Error Summary}.
     * 
     * <DIV CLASS=HTML>{@code
     * <li class="blockList">
     *  <table class="typeSummary">
     *  <caption><span>Error Summary</span><span class="tabEnd">&nbsp;</span></caption>
     *  <tr>
     * ...
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The "Error Summary" section of the "Package Summary", or null if the
     * package-summary page provided did not have an "Error Summary" section
     */
    public static DotPair errors(Vector<HTMLNode> fileVec)
    { return typeSummary(fileVec, "Error Summary"); }

    /**
     * Returns an instance of {@code DotPair} which points to an HTML {@code <TABLE>} element,
     * where that table has {@code CLASS=typeSummary} and contains a caption with the text
     * {@code Annotation Types Summary}.
     * 
     * <DIV CLASS=HTML>{@code
     * <li class="blockList">
     *  <table class="typeSummary">
     *  <caption><span>Annotation Types Summary</span><span class="tabEnd">&nbsp;</span></caption>
     *  <tr>
     * ...
     * }</DIV>
     * 
     * @param fileVec The vectorized-HTML for a Java Doc Generated "Package Summary" Web-Page.
     * 
     * @return The "Annotation Types Summary" section of the "Package Summary", or null if the
     * package-summary page provided did not have an "Error Summary" section
     */
    public static DotPair annotations(Vector<HTMLNode> fileVec)
    { return typeSummary(fileVec, "Annotation Types Summary"); }

    private static DotPair typeSummary(Vector<HTMLNode> fileVec, String type)
    {
        HNLIInclusive iter = InnerTagInclusiveIterator.get
            (fileVec, "table", "class", TextComparitor.C, "typeSummary");

        while (iter.hasNext())
        {
            DotPair     table   = iter.nextDotPair();
            DotPair     dp      = TagNodeFindInclusive.first(fileVec, table.start, table.end, "caption");
            HTMLNode    n;

            for (int pos = dp.start; pos < dp.end; pos++)
                if ((n = fileVec.elementAt(pos)).isTextNode())
                    if (n.str.equals(type))
                        return table;
        }

        return null;
    }
}