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