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