AbstractModuleIndexWriter.java revision 3595:81692f730015 
1/*
2 * Copyright (c) 2013, 2016, 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
26package jdk.javadoc.internal.doclets.formats.html;
27
28import java.io.*;
29import java.util.Map;
30import java.util.Set;
31import java.util.SortedMap;
32
33import javax.lang.model.element.ModuleElement;
34import javax.lang.model.element.PackageElement;
35
36import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
37import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
41import jdk.javadoc.internal.doclets.toolkit.Content;
42import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
43
44/**
45 * Abstract class to generate the module overview files in
46 * Frame and Non-Frame format. This will be sub-classed to
47 * generate module-overview-frame.html as well as module-overview-summary.html.
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 */
56public abstract class AbstractModuleIndexWriter extends HtmlDocletWriter {
57
58    /**
59     * Modules to be documented.
60     */
61    protected SortedMap<ModuleElement, Set<PackageElement>> modules;
62
63    /**
64     * Constructor. Also initializes the modules variable.
65     *
66     * @param configuration  The current configuration
67     * @param filename Name of the module index file to be generated.
68     */
69    public AbstractModuleIndexWriter(ConfigurationImpl configuration,
70                                      DocPath filename) {
71        super(configuration, filename);
72        modules = configuration.modulePackages;
73    }
74
75    /**
76     * Adds the navigation bar header to the documentation tree.
77     *
78     * @param body the document tree to which the navigation bar header will be added
79     */
80    protected abstract void addNavigationBarHeader(Content body);
81
82    /**
83     * Adds the navigation bar footer to the documentation tree.
84     *
85     * @param body the document tree to which the navigation bar footer will be added
86     */
87    protected abstract void addNavigationBarFooter(Content body);
88
89    /**
90     * Adds the overview header to the documentation tree.
91     *
92     * @param body the document tree to which the overview header will be added
93     */
94    protected abstract void addOverviewHeader(Content body);
95
96    /**
97     * Adds the modules list to the documentation tree.
98     *
99     * @param modules the set of modules
100     * @param text caption for the table
101     * @param tableSummary summary for the table
102     * @param body the document tree to which the modules list will be added
103     */
104    protected abstract void addModulesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
105            String tableSummary, Content body);
106
107    /**
108     * Adds the module packages list to the documentation tree.
109     *
110     * @param modules the set of modules
111     * @param text caption for the table
112     * @param tableSummary summary for the table
113     * @param body the document tree to which the modules list will be added
114     * @param mdle the module being documented
115     */
116    protected abstract void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
117            String tableSummary, Content body, ModuleElement mdle);
118
119    /**
120     * Generate and prints the contents in the module index file. Call appropriate
121     * methods from the sub-class in order to generate Frame or Non
122     * Frame format.
123     *
124     * @param title the title of the window.
125     * @param includeScript boolean set true if windowtitle script is to be included
126     */
127    protected void buildModuleIndexFile(String title, boolean includeScript) throws IOException {
128        String windowOverview = configuration.getText(title);
129        Content body = getBody(includeScript, getWindowTitle(windowOverview));
130        addNavigationBarHeader(body);
131        addOverviewHeader(body);
132        addIndex(body);
133        addOverview(body);
134        addNavigationBarFooter(body);
135        printHtmlDocument(configuration.metakeywords.getOverviewMetaKeywords(title,
136                configuration.doctitle), includeScript, body);
137    }
138
139    /**
140     * Generate and prints the contents in the module packages index file. Call appropriate
141     * methods from the sub-class in order to generate Frame or Non
142     * Frame format.
143     *
144     * @param title the title of the window.
145     * @param includeScript boolean set true if windowtitle script is to be included
146     * @param mdle the name of the module being documented
147     */
148    protected void buildModulePackagesIndexFile(String title,
149            boolean includeScript, ModuleElement mdle) throws IOException {
150        String windowOverview = configuration.getText(title);
151        Content body = getBody(includeScript, getWindowTitle(windowOverview));
152        addNavigationBarHeader(body);
153        addOverviewHeader(body);
154        addModulePackagesIndex(body, mdle);
155        addOverview(body);
156        addNavigationBarFooter(body);
157        printHtmlDocument(configuration.metakeywords.getOverviewMetaKeywords(title,
158                configuration.doctitle), includeScript, body);
159    }
160
161    /**
162     * Default to no overview, override to add overview.
163     *
164     * @param body the document tree to which the overview will be added
165     */
166    protected void addOverview(Content body) throws IOException {
167    }
168
169    /**
170     * Adds the frame or non-frame module index to the documentation tree.
171     *
172     * @param body the document tree to which the index will be added
173     */
174    protected void addIndex(Content body) {
175        addIndexContents(modules, "doclet.Module_Summary",
176                configuration.getText("doclet.Member_Table_Summary",
177                configuration.getText("doclet.Module_Summary"),
178                configuration.getText("doclet.modules")), body);
179    }
180
181    /**
182     * Adds the frame or non-frame module packages index to the documentation tree.
183     *
184     * @param body the document tree to which the index will be added
185     * @param mdle the module being documented
186     */
187    protected void addModulePackagesIndex(Content body, ModuleElement mdle) {
188        addModulePackagesIndexContents("doclet.Module_Summary",
189                configuration.getText("doclet.Member_Table_Summary",
190                configuration.getText("doclet.Module_Summary"),
191                configuration.getText("doclet.modules")), body, mdle);
192    }
193
194    /**
195     * Adds module index contents. Call appropriate methods from
196     * the sub-classes. Adds it to the body HtmlTree
197     *
198     * @param modules the modules to be documented
199     * @param text string which will be used as the heading
200     * @param tableSummary summary for the table
201     * @param body the document tree to which the index contents will be added
202     */
203    protected void addIndexContents(Map<ModuleElement, Set<PackageElement>> modules, String text,
204            String tableSummary, Content body) {
205        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.NAV))
206                ? HtmlTree.NAV()
207                : new HtmlTree(HtmlTag.DIV);
208        htmlTree.addStyle(HtmlStyle.indexNav);
209        HtmlTree ul = new HtmlTree(HtmlTag.UL);
210        addAllClassesLink(ul);
211        addAllPackagesLink(ul);
212        htmlTree.addContent(ul);
213        body.addContent(htmlTree);
214        addModulesList(modules, text, tableSummary, body);
215    }
216
217    /**
218     * Adds module packages index contents. Call appropriate methods from
219     * the sub-classes. Adds it to the body HtmlTree
220     *
221     * @param text string which will be used as the heading
222     * @param tableSummary summary for the table
223     * @param body the document tree to which the index contents will be added
224     * @param mdle the module being documented
225     */
226    protected void addModulePackagesIndexContents(String text,
227            String tableSummary, Content body, ModuleElement mdle) {
228        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.NAV))
229                ? HtmlTree.NAV()
230                : new HtmlTree(HtmlTag.DIV);
231        htmlTree.addStyle(HtmlStyle.indexNav);
232        HtmlTree ul = new HtmlTree(HtmlTag.UL);
233        addAllClassesLink(ul);
234        addAllPackagesLink(ul);
235        addAllModulesLink(ul);
236        htmlTree.addContent(ul);
237        body.addContent(htmlTree);
238        addModulePackagesList(modules, text, tableSummary, body, mdle);
239    }
240
241    /**
242     * Adds the doctitle to the documentation tree, if it is specified on the command line.
243     *
244     * @param body the document tree to which the title will be added
245     */
246    protected void addConfigurationTitle(Content body) {
247        if (configuration.doctitle.length() > 0) {
248            Content title = new RawHtml(configuration.doctitle);
249            Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING,
250                    HtmlStyle.title, title);
251            Content div = HtmlTree.DIV(HtmlStyle.header, heading);
252            body.addContent(div);
253        }
254    }
255
256    /**
257     * Returns highlighted "Overview", in the navigation bar as this is the
258     * overview page.
259     *
260     * @return a Content object to be added to the documentation tree
261     */
262    protected Content getNavLinkContents() {
263        Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.overviewLabel);
264        return li;
265    }
266
267    /**
268     * Do nothing. This will be overridden in ModuleIndexFrameWriter.
269     *
270     * @param div the document tree to which the all classes link will be added
271     */
272    protected void addAllClassesLink(Content div) {
273    }
274
275    /**
276     * Do nothing. This will be overridden in ModuleIndexFrameWriter.
277     *
278     * @param div the document tree to which the all packages link will be added
279     */
280    protected void addAllPackagesLink(Content div) {
281    }
282
283    /**
284     * Do nothing. This will be overridden in ModulePackageIndexFrameWriter.
285     *
286     * @param div the document tree to which the all modules link will be added
287     */
288    protected void addAllModulesLink(Content div) {
289    }
290}
291