1 /*
2 * Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.javadoc.internal.doclets.formats.html;
27
28 import java.util.*;
29
30 import javax.lang.model.element.ModuleElement;
31 import javax.lang.model.element.PackageElement;
32
33 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
35 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
37 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
38 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
39 import jdk.javadoc.internal.doclets.toolkit.Content;
40 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
41 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
42 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
43 import jdk.javadoc.internal.doclets.toolkit.util.Group;
44
45 /**
46 * Generate the module index page "overview-summary.html" for the right-hand
47 * frame.
48 *
49 * <p><b>This is NOT part of any supported API.
50 * If you write code that depends on this, you do so at your own risk.
51 * This code and its internal interfaces are subject to change or
52 * deletion without notice.</b>
53 *
54 * @author Bhavesh Patel
55 */
56 public class ModuleIndexWriter extends AbstractModuleIndexWriter {
57
58 /**
59 * Map representing the group of modules as specified on the command line.
60 *
61 * @see Group
62 */
63 private final Map<String, SortedSet<ModuleElement>> groupModuleMap;
64
65 /**
66 * List to store the order groups as specified on the command line.
67 */
68 private final List<String> groupList;
69
70 /**
71 * HTML tree for main tag.
72 */
73 private final HtmlTree htmlTree = HtmlTree.MAIN();
74
75 /**
76 * Construct the ModuleIndexWriter.
77 * @param configuration the configuration object
78 * @param filename the name of the generated file
79 */
80 public ModuleIndexWriter(HtmlConfiguration configuration, DocPath filename) {
81 super(configuration, filename);
82 groupModuleMap = configuration.group.groupModules(configuration.modules);
83 groupList = configuration.group.getGroupList();
84 }
85
86 /**
87 * Generate the module index page for the right-hand frame.
88 *
89 * @param configuration the current configuration of the doclet.
90 * @throws DocFileIOException if there is a problem generating the module index page
91 */
92 public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
93 DocPath filename = DocPaths.overviewSummary(configuration.frames);
94 ModuleIndexWriter mdlgen = new ModuleIndexWriter(configuration, filename);
95 mdlgen.buildModuleIndexFile("doclet.Window_Overview_Summary", true);
96 }
97
98 /**
99 * Add the module index.
100 *
101 * @param body the documentation tree to which the index will be added
102 */
103 @Override
104 protected void addIndex(Content body) {
105 for (String groupname : groupList) {
106 SortedSet<ModuleElement> list = groupModuleMap.get(groupname);
107 if (list != null && !list.isEmpty()) {
108 addIndexContents(list,
109 groupname, configuration.getText("doclet.Member_Table_Summary",
110 groupname, configuration.getText("doclet.modules")), body);
111 }
112 }
113 }
114
115 /**
116 * Adds module index contents.
117 *
118 * @param title the title of the section
119 * @param tableSummary summary for the table
120 * @param body the document tree to which the index contents will be added
121 */
122 protected void addIndexContents(Collection<ModuleElement> modules, String title, String tableSummary, Content body) {
123 HtmlTree htmltree = (configuration.allowTag(HtmlTag.NAV))
124 ? HtmlTree.NAV()
125 : new HtmlTree(HtmlTag.DIV);
126 htmltree.addStyle(HtmlStyle.indexNav);
127 HtmlTree ul = new HtmlTree(HtmlTag.UL);
128 addAllClassesLink(ul);
129 if (configuration.showModules) {
130 addAllModulesLink(ul);
131 }
132 htmltree.addContent(ul);
133 body.addContent(htmltree);
134 addModulesList(modules, title, tableSummary, body);
135 }
136
137 /**
138 * Add the list of modules.
139 *
140 * @param text The table caption
141 * @param tableSummary the summary of the table tag
142 * @param body the content tree to which the module list will be added
143 */
144 protected void addModulesList(Collection<ModuleElement> modules, String text, String tableSummary, Content body) {
145 Content table = (configuration.isOutputHtml5())
146 ? HtmlTree.TABLE(HtmlStyle.overviewSummary, getTableCaption(new RawHtml(text)))
147 : HtmlTree.TABLE(HtmlStyle.overviewSummary, tableSummary, getTableCaption(new RawHtml(text)));
148 table.addContent(getSummaryTableHeader(moduleTableHeader, "col"));
149 Content tbody = new HtmlTree(HtmlTag.TBODY);
150 addModulesList(modules, tbody);
151 table.addContent(tbody);
152 Content anchor = getMarkerAnchor(text);
153 Content div = HtmlTree.DIV(HtmlStyle.contentContainer, anchor);
154 div.addContent(table);
155 if (configuration.allowTag(HtmlTag.MAIN)) {
156 htmlTree.addContent(div);
157 } else {
158 body.addContent(div);
159 }
160 }
161
162 /**
163 * Adds list of modules in the index table. Generate link to each module.
164 *
165 * @param tbody the documentation tree to which the list will be added
166 */
167 protected void addModulesList(Collection<ModuleElement> modules, Content tbody) {
168 boolean altColor = true;
169 for (ModuleElement mdle : modules) {
170 if (!mdle.isUnnamed()) {
171 Content moduleLinkContent = getModuleLink(mdle, new StringContent(mdle.getQualifiedName().toString()));
172 Content thModule = HtmlTree.TH_ROW_SCOPE(HtmlStyle.colFirst, moduleLinkContent);
173 HtmlTree tdSummary = new HtmlTree(HtmlTag.TD);
174 tdSummary.addStyle(HtmlStyle.colLast);
175 addSummaryComment(mdle, tdSummary);
176 HtmlTree tr = HtmlTree.TR(thModule);
177 tr.addContent(tdSummary);
178 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor);
179 tbody.addContent(tr);
180 }
181 altColor = !altColor;
182 }
183 }
184
185 /**
186 * Adds the overview summary comment for this documentation. Add one line
187 * summary at the top of the page and generate a link to the description,
188 * which is added at the end of this page.
189 *
190 * @param body the documentation tree to which the overview header will be added
191 */
192 @Override
193 protected void addOverviewHeader(Content body) {
194 addConfigurationTitle(body);
195 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) {
196 HtmlTree div = new HtmlTree(HtmlTag.DIV);
197 div.addStyle(HtmlStyle.contentContainer);
198 addOverviewComment(div);
199 if (configuration.allowTag(HtmlTag.MAIN)) {
200 htmlTree.addContent(div);
201 } else {
202 body.addContent(div);
203 }
204 }
205 }
206
207 /**
208 * Adds the overview comment as provided in the file specified by the
209 * "-overview" option on the command line.
210 *
211 * @param htmltree the documentation tree to which the overview comment will
212 * be added
213 */
214 protected void addOverviewComment(Content htmltree) {
215 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) {
216 addInlineComment(configuration.overviewElement, htmltree);
217 }
218 }
219
220 /**
221 * For HTML 5, add the htmlTree to the body. For HTML 4, do nothing.
222 *
223 * @param body the documentation tree to which the overview will be added
224 */
225 @Override
226 protected void addOverview(Content body) {
227 if (configuration.allowTag(HtmlTag.MAIN)) {
228 body.addContent(htmlTree);
229 }
230 }
231
232 /**
233 * Adds the top text (from the -top option), the upper
234 * navigation bar, and then the title (from the"-title"
235 * option), at the top of page.
236 *
237 * @param body the documentation tree to which the navigation bar header will be added
238 */
239 @Override
240 protected void addNavigationBarHeader(Content body) {
241 Content htmlTree = (configuration.allowTag(HtmlTag.HEADER))
242 ? HtmlTree.HEADER()
243 : body;
244 addTop(htmlTree);
245 addNavLinks(true, htmlTree);
246 if (configuration.allowTag(HtmlTag.HEADER)) {
247 body.addContent(htmlTree);
248 }
249 }
250
251 /**
252 * Adds the lower navigation bar and the bottom text
253 * (from the -bottom option) at the bottom of page.
254 *
255 * @param body the documentation tree to which the navigation bar footer will be added
256 */
257 @Override
258 protected void addNavigationBarFooter(Content body) {
259 Content htmltree = (configuration.allowTag(HtmlTag.FOOTER))
260 ? HtmlTree.FOOTER()
261 : body;
262 addNavLinks(false, htmltree);
263 addBottom(htmltree);
264 if (configuration.allowTag(HtmlTag.FOOTER)) {
265 body.addContent(htmltree);
266 }
267 }
268
269 @Override
270 protected void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
271 String tableSummary, Content body, ModuleElement mdle) {
272 }
273 }