1 /*
2  * Copyright (c) 2013, 2018, 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.ArrayList;
29 import java.util.List;
30 import java.util.Map;
31 import java.util.Set;
32 
33 import javax.lang.model.element.ModuleElement;
34 import javax.lang.model.element.PackageElement;
35 
36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
41 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
42 import jdk.javadoc.internal.doclets.toolkit.Content;
43 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
44 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
45 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
46 
47 /**
48  * Generate the module package index for the left-hand frame in the generated output.
49  * A click on the package name in this frame will update the page in the bottom
50  * left hand frame with the listing of contents of the clicked module package.
51  *
52  *  <p><b>This is NOT part of any supported API.
53  *  If you write code that depends on this, you do so at your own risk.
54  *  This code and its internal interfaces are subject to change or
55  *  deletion without notice.</b>
56  *
57  * @author Bhavesh Patel
58  */
59 public class ModulePackageIndexFrameWriter extends AbstractModuleIndexWriter {
60 
61     /**
62      * Construct the ModulePackageIndexFrameWriter object.
63      *
64      * @param configuration the configuration object
65      * @param filename Name of the package index file to be generated.
66      */
ModulePackageIndexFrameWriter(HtmlConfiguration configuration, DocPath filename)67     public ModulePackageIndexFrameWriter(HtmlConfiguration configuration, DocPath filename)  {
68         super(configuration, filename);
69     }
70 
71     /**
72      * Generate the module package index file.
73      * @throws DocFileIOException
74      * @param configuration the configuration object
75      * @param mdle the module being documented
76      */
generate(HtmlConfiguration configuration, ModuleElement mdle)77     public static void generate(HtmlConfiguration configuration, ModuleElement mdle) throws DocFileIOException {
78         DocPath filename = configuration.docPaths.moduleFrame(mdle);
79         ModulePackageIndexFrameWriter modpackgen = new ModulePackageIndexFrameWriter(configuration, filename);
80         modpackgen.buildModulePackagesIndexFile("doclet.Window_Overview", false, mdle);
81     }
82 
83     /**
84      * {@inheritDoc}
85      */
addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text, String tableSummary, Content body, ModuleElement mdle)86     protected void addModulePackagesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
87             String tableSummary, Content body, ModuleElement mdle) {
88         Content profNameContent = new StringContent(mdle.getQualifiedName().toString());
89         Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true,
90                 getTargetModuleLink("classFrame", profNameContent, mdle));
91         heading.addContent(Contents.SPACE);
92         heading.addContent(contents.packagesLabel);
93         HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN))
94                 ? HtmlTree.MAIN(HtmlStyle.indexContainer, heading)
95                 : HtmlTree.DIV(HtmlStyle.indexContainer, heading);
96         HtmlTree ul = new HtmlTree(HtmlTag.UL);
97         ul.setTitle(contents.packagesLabel);
98         List<PackageElement> packages = new ArrayList<>(modules.get(mdle));
99         for (PackageElement pkg : packages) {
100             if ((!(configuration.nodeprecated && utils.isDeprecated(pkg)))) {
101                 ul.addContent(getPackage(pkg, mdle));
102             }
103         }
104         htmlTree.addContent(ul);
105         body.addContent(htmlTree);
106     }
107 
108     /**
109      * {@inheritDoc}
110      */
addModulePackagesList(Set<ModuleElement> modules, String text, String tableSummary, Content body, ModuleElement mdle)111     protected void addModulePackagesList(Set<ModuleElement> modules, String text,
112             String tableSummary, Content body, ModuleElement mdle) {
113         Content moduleNameContent = new StringContent(mdle.getQualifiedName().toString());
114         Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true,
115                 getTargetModuleLink("classFrame", moduleNameContent, mdle));
116         heading.addContent(Contents.SPACE);
117         heading.addContent(contents.packagesLabel);
118         HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN))
119                 ? HtmlTree.MAIN(HtmlStyle.indexContainer, heading)
120                 : HtmlTree.DIV(HtmlStyle.indexContainer, heading);
121         HtmlTree ul = new HtmlTree(HtmlTag.UL);
122         ul.setTitle(contents.packagesLabel);
123         Set<PackageElement> modulePackages = configuration.modulePackages.get(mdle);
124         for (PackageElement pkg: modulePackages) {
125             if ((!(configuration.nodeprecated && utils.isDeprecated(pkg)))) {
126                 ul.addContent(getPackage(pkg, mdle));
127             }
128         }
129         htmlTree.addContent(ul);
130         body.addContent(htmlTree);
131     }
132 
133     /**
134      * Returns each package name as a separate link.
135      *
136      * @param pkg PackageElement
137      * @param mdle the module being documented
138      * @return content for the package link
139      */
getPackage(PackageElement pkg, ModuleElement mdle)140     protected Content getPackage(PackageElement pkg, ModuleElement mdle) {
141         Content packageLinkContent;
142         Content pkgLabel;
143         if (!pkg.isUnnamed()) {
144             pkgLabel = getPackageLabel(utils.getPackageName(pkg));
145             packageLinkContent = links.createLink(pathString(pkg,
146                      DocPaths.PACKAGE_FRAME), pkgLabel, "",
147                     "packageFrame");
148         } else {
149             pkgLabel = new StringContent("<unnamed package>");
150             packageLinkContent = links.createLink(DocPaths.PACKAGE_FRAME,
151                     pkgLabel, "", "packageFrame");
152         }
153         Content li = HtmlTree.LI(packageLinkContent);
154         return li;
155     }
156 
157     /**
158      * {@inheritDoc}
159      */
addNavigationBarHeader(Content body)160     protected void addNavigationBarHeader(Content body) {
161         Content headerContent;
162         if (configuration.packagesheader.length() > 0) {
163             headerContent = new RawHtml(replaceDocRootDir(configuration.packagesheader));
164         } else {
165             headerContent = new RawHtml(replaceDocRootDir(configuration.header));
166         }
167         Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true,
168                 HtmlStyle.bar, headerContent);
169         body.addContent(heading);
170     }
171 
172     /**
173      * Do nothing as there is no overview information in this page.
174      */
addOverviewHeader(Content body)175     protected void addOverviewHeader(Content body) {
176     }
177 
178     /**
179      * Do nothing as there is no modules list on this page.
180      */
addModulesList(Content body)181     protected void addModulesList(Content body) {
182     }
183 
184     /**
185      * Adds "All Classes" link for the top of the left-hand frame page to the
186      * documentation tree.
187      *
188      * @param ul the Content object to which the all classes link should be added
189      */
addAllClassesLink(Content ul)190     protected void addAllClassesLink(Content ul) {
191         DocPath allClassesFrame = configuration.useModuleDirectories
192                 ? DocPaths.DOT_DOT.resolve(DocPaths.ALLCLASSES_FRAME)
193                 : DocPaths.ALLCLASSES_FRAME;
194         Content linkContent = links.createLink(allClassesFrame,
195                 contents.allClassesLabel, "", "packageFrame");
196         Content li = HtmlTree.LI(linkContent);
197         ul.addContent(li);
198     }
199 
200     /**
201      * Adds "All Packages" link for the top of the left-hand frame page to the
202      * documentation tree.
203      *
204      * @param ul the Content object to which the all packages link should be added
205      */
addAllPackagesLink(Content ul)206     protected void addAllPackagesLink(Content ul) {
207         DocPath overviewFrame = configuration.useModuleDirectories
208                 ? DocPaths.DOT_DOT.resolve(DocPaths.OVERVIEW_FRAME)
209                 : DocPaths.OVERVIEW_FRAME;
210         Content linkContent = links.createLink(overviewFrame,
211                 contents.allPackagesLabel, "", "packageListFrame");
212         Content li = HtmlTree.LI(linkContent);
213         ul.addContent(li);
214     }
215 
216     /**
217      * Adds "All Modules" link for the top of the left-hand frame page to the
218      * documentation tree.
219      *
220      * @param ul the Content object to which the all modules link should be added
221      */
addAllModulesLink(Content ul)222     protected void addAllModulesLink(Content ul) {
223         DocPath moduleOverviewFrame = configuration.useModuleDirectories
224                 ? DocPaths.DOT_DOT.resolve(DocPaths.MODULE_OVERVIEW_FRAME)
225                 : DocPaths.MODULE_OVERVIEW_FRAME;
226         Content linkContent = links.createLink(moduleOverviewFrame,
227                 contents.allModulesLabel, "", "packageListFrame");
228         Content li = HtmlTree.LI(linkContent);
229         ul.addContent(li);
230     }
231 
232     /**
233      * {@inheritDoc}
234      */
addNavigationBarFooter(Content body)235     protected void addNavigationBarFooter(Content body) {
236         Content p = HtmlTree.P(Contents.SPACE);
237         body.addContent(p);
238     }
239 }
240