1 /* 2 * Copyright (c) 1997, 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.PackageElement; 31 32 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; 33 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 35 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 36 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; 37 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 38 import jdk.javadoc.internal.doclets.toolkit.Content; 39 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; 40 import jdk.javadoc.internal.doclets.toolkit.util.DocPath; 41 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 42 import jdk.javadoc.internal.doclets.toolkit.util.Group; 43 44 /** 45 * Generate the package index page "overview-summary.html" for the right-hand 46 * frame. A click on the package name on this page will update the same frame 47 * with the "package-summary.html" file for the clicked package. 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 Atul M Dambalkar 55 * @author Bhavesh Patel (Modified) 56 */ 57 public class PackageIndexWriter extends AbstractPackageIndexWriter { 58 59 60 /** 61 * Map representing the group of packages as specified on the command line. 62 * 63 * @see Group 64 */ 65 private final Map<String, SortedSet<PackageElement>> groupPackageMap; 66 67 /** 68 * List to store the order groups as specified on the command line. 69 */ 70 private final List<String> groupList; 71 72 /** 73 * HTML tree for main tag. 74 */ 75 private final HtmlTree htmlTree = HtmlTree.MAIN(); 76 77 /** 78 * Construct the PackageIndexWriter. Also constructs the grouping 79 * information as provided on the command line by "-group" option. Stores 80 * the order of groups specified by the user. 81 * 82 * @param configuration the configuration for this doclet 83 * @param filename the path of the page to be generated 84 * @see Group 85 */ 86 public PackageIndexWriter(HtmlConfiguration configuration, DocPath filename) { 87 super(configuration, filename); 88 groupPackageMap = configuration.group.groupPackages(packages); 89 groupList = configuration.group.getGroupList(); 90 } 91 92 /** 93 * Generate the package index page for the right-hand frame. 94 * 95 * @param configuration the current configuration of the doclet. 96 * @throws DocFileIOException if there is a problem generating the package index page 97 */ 98 public static void generate(HtmlConfiguration configuration) throws DocFileIOException { 99 DocPath filename = DocPaths.overviewSummary(configuration.frames); 100 PackageIndexWriter packgen = new PackageIndexWriter(configuration, filename); 101 packgen.buildPackageIndexFile("doclet.Window_Overview_Summary", true); 102 } 103 104 /** 105 * Depending upon the grouping information and their titles, add 106 * separate table indices for each package group. 107 * 108 * @param body the documentation tree to which the index will be added 109 */ 110 @Override 111 protected void addIndex(Content body) { 112 for (String groupname : groupList) { 113 SortedSet<PackageElement> list = groupPackageMap.get(groupname); 114 if (list != null && !list.isEmpty()) { 115 addIndexContents(list, 116 groupname, configuration.getText("doclet.Member_Table_Summary", 117 groupname, configuration.getText("doclet.packages")), body); 118 } 119 } 120 } 121 122 /** 123 * {@inheritDoc} 124 */ 125 @Override 126 protected void addPackagesList(Collection<PackageElement> packages, String text, 127 String tableSummary, Content body) { 128 Content table = (configuration.isOutputHtml5()) 129 ? HtmlTree.TABLE(HtmlStyle.overviewSummary, getTableCaption(new RawHtml(text))) 130 : HtmlTree.TABLE(HtmlStyle.overviewSummary, tableSummary, getTableCaption(new RawHtml(text))); 131 table.addContent(getSummaryTableHeader(packageTableHeader, "col")); 132 Content tbody = new HtmlTree(HtmlTag.TBODY); 133 addPackagesList(packages, tbody); 134 table.addContent(tbody); 135 Content anchor = getMarkerAnchor(text); 136 Content div = HtmlTree.DIV(HtmlStyle.contentContainer, anchor); 137 div.addContent(table); 138 if (configuration.allowTag(HtmlTag.MAIN)) { 139 htmlTree.addContent(div); 140 } else { 141 body.addContent(div); 142 } 143 } 144 145 /** 146 * Adds list of packages in the index table. Generate link to each package. 147 * 148 * @param packages Packages to which link is to be generated 149 * @param tbody the documentation tree to which the list will be added 150 */ 151 protected void addPackagesList(Collection<PackageElement> packages, Content tbody) { 152 boolean altColor = true; 153 for (PackageElement pkg : packages) { 154 if (!pkg.isUnnamed()) { 155 if (!(configuration.nodeprecated && utils.isDeprecated(pkg))) { 156 Content packageLinkContent = getPackageLink(pkg, getPackageName(pkg)); 157 Content thPackage = HtmlTree.TH_ROW_SCOPE(HtmlStyle.colFirst, packageLinkContent); 158 HtmlTree tdSummary = new HtmlTree(HtmlTag.TD); 159 tdSummary.addStyle(HtmlStyle.colLast); 160 addSummaryComment(pkg, tdSummary); 161 HtmlTree tr = HtmlTree.TR(thPackage); 162 tr.addContent(tdSummary); 163 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor); 164 tbody.addContent(tr); 165 } 166 } 167 altColor = !altColor; 168 } 169 } 170 171 /** 172 * Adds the overview summary comment for this documentation. Add one line 173 * summary at the top of the page and generate a link to the description, 174 * which is added at the end of this page. 175 * 176 * @param body the documentation tree to which the overview header will be added 177 */ 178 @Override 179 protected void addOverviewHeader(Content body) { 180 addConfigurationTitle(body); 181 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) { 182 HtmlTree div = new HtmlTree(HtmlTag.DIV); 183 div.addStyle(HtmlStyle.contentContainer); 184 addOverviewComment(div); 185 if (configuration.allowTag(HtmlTag.MAIN)) { 186 htmlTree.addContent(div); 187 } else { 188 body.addContent(div); 189 } 190 } 191 } 192 193 /** 194 * Adds the overview comment as provided in the file specified by the 195 * "-overview" option on the command line. 196 * 197 * @param htmltree the documentation tree to which the overview comment will 198 * be added 199 */ 200 protected void addOverviewComment(Content htmltree) { 201 if (!utils.getFullBody(configuration.overviewElement).isEmpty()) { 202 addInlineComment(configuration.overviewElement, htmltree); 203 } 204 } 205 206 /** 207 * For HTML 5, add the htmlTree to the body. For HTML 4, do nothing. 208 * 209 * @param body the documentation tree to which the overview will be added 210 */ 211 @Override 212 protected void addOverview(Content body) { 213 if (configuration.allowTag(HtmlTag.MAIN)) { 214 body.addContent(htmlTree); 215 } 216 } 217 218 /** 219 * Adds the top text (from the -top option), the upper 220 * navigation bar, and then the title (from the"-title" 221 * option), at the top of page. 222 * 223 * @param body the documentation tree to which the navigation bar header will be added 224 */ 225 @Override 226 protected void addNavigationBarHeader(Content body) { 227 Content htmlTree = (configuration.allowTag(HtmlTag.HEADER)) 228 ? HtmlTree.HEADER() 229 : body; 230 addTop(htmlTree); 231 addNavLinks(true, htmlTree); 232 if (configuration.allowTag(HtmlTag.HEADER)) { 233 body.addContent(htmlTree); 234 } 235 } 236 237 /** 238 * Adds the lower navigation bar and the bottom text 239 * (from the -bottom option) at the bottom of page. 240 * 241 * @param body the documentation tree to which the navigation bar footer will be added 242 */ 243 @Override 244 protected void addNavigationBarFooter(Content body) { 245 Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER)) 246 ? HtmlTree.FOOTER() 247 : body; 248 addNavLinks(false, htmlTree); 249 addBottom(htmlTree); 250 if (configuration.allowTag(HtmlTag.FOOTER)) { 251 body.addContent(htmlTree); 252 } 253 } 254 }