1/* 2 * Copyright (c) 2001, 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 26package jdk.javadoc.internal.doclets.formats.html; 27 28import java.util.*; 29 30import javax.lang.model.element.Modifier; 31import javax.lang.model.element.PackageElement; 32import javax.lang.model.element.TypeElement; 33import javax.lang.model.element.VariableElement; 34 35import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; 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.StringContent; 41import jdk.javadoc.internal.doclets.toolkit.ConstantsSummaryWriter; 42import jdk.javadoc.internal.doclets.toolkit.Content; 43import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; 44import jdk.javadoc.internal.doclets.toolkit.util.DocLink; 45import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 46 47 48/** 49 * Write the Constants Summary Page in HTML format. 50 * 51 * <p><b>This is NOT part of any supported API. 52 * If you write code that depends on this, you do so at your own risk. 53 * This code and its internal interfaces are subject to change or 54 * deletion without notice.</b> 55 * 56 * @author Jamie Ho 57 * @author Bhavesh Patel (Modified) 58 */ 59public class ConstantsSummaryWriterImpl extends HtmlDocletWriter implements ConstantsSummaryWriter { 60 61 /** 62 * The configuration used in this run of the standard doclet. 63 */ 64 HtmlConfiguration configuration; 65 66 /** 67 * The current class being documented. 68 */ 69 private TypeElement currentTypeElement; 70 71 private final String constantsTableSummary; 72 73 private final List<String> constantsTableHeader; 74 75 /** 76 * The HTML tree for main tag. 77 */ 78 private HtmlTree mainTree = HtmlTree.MAIN(); 79 80 /** 81 * The HTML tree for constant values summary. 82 */ 83 private HtmlTree summaryTree; 84 85 /** 86 * Construct a ConstantsSummaryWriter. 87 * @param configuration the configuration used in this run 88 * of the standard doclet. 89 */ 90 public ConstantsSummaryWriterImpl(HtmlConfiguration configuration) { 91 super(configuration, DocPaths.CONSTANT_VALUES); 92 this.configuration = configuration; 93 constantsTableSummary = configuration.getText("doclet.Constants_Table_Summary", 94 configuration.getText("doclet.Constants_Summary")); 95 constantsTableHeader = new ArrayList<>(); 96 constantsTableHeader.add(getModifierTypeHeader()); 97 constantsTableHeader.add(configuration.getText("doclet.ConstantField")); 98 constantsTableHeader.add(configuration.getText("doclet.Value")); 99 } 100 101 /** 102 * {@inheritDoc} 103 */ 104 public Content getHeader() { 105 String label = configuration.getText("doclet.Constants_Summary"); 106 HtmlTree bodyTree = getBody(true, getWindowTitle(label)); 107 HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) 108 ? HtmlTree.HEADER() 109 : bodyTree; 110 addTop(htmlTree); 111 addNavLinks(true, htmlTree); 112 if (configuration.allowTag(HtmlTag.HEADER)) { 113 bodyTree.addContent(htmlTree); 114 } 115 return bodyTree; 116 } 117 118 /** 119 * {@inheritDoc} 120 */ 121 public Content getContentsHeader() { 122 return new HtmlTree(HtmlTag.UL); 123 } 124 125 /** 126 * {@inheritDoc} 127 */ 128 public void addLinkToPackageContent(PackageElement pkg, 129 Set<PackageElement> printedPackageHeaders, Content contentListTree) { 130 //add link to summary 131 Content link; 132 if (pkg.isUnnamed()) { 133 link = getHyperLink(getDocLink( 134 SectionName.UNNAMED_PACKAGE_ANCHOR), 135 contents.defaultPackageLabel, "", ""); 136 } else { 137 String parsedPackageName = utils.parsePackageName(pkg); 138 Content packageNameContent = getPackageLabel(parsedPackageName); 139 packageNameContent.addContent(".*"); 140 link = getHyperLink(DocLink.fragment(parsedPackageName), 141 packageNameContent, "", ""); 142 PackageElement abbrevPkg = configuration.workArounds.getAbbreviatedPackageElement(pkg); 143 printedPackageHeaders.add(abbrevPkg); 144 } 145 contentListTree.addContent(HtmlTree.LI(link)); 146 } 147 148 /** 149 * {@inheritDoc} 150 */ 151 public void addContentsList(Content contentTree, Content contentListTree) { 152 Content titleContent = contents.constantsSummaryTitle; 153 Content pHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true, 154 HtmlStyle.title, titleContent); 155 Content div = HtmlTree.DIV(HtmlStyle.header, pHeading); 156 Content headingContent = contents.contentsHeading; 157 Content heading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, true, 158 headingContent); 159 if (configuration.allowTag(HtmlTag.SECTION)) { 160 HtmlTree section = HtmlTree.SECTION(heading); 161 section.addContent(contentListTree); 162 div.addContent(section); 163 mainTree.addContent(div); 164 } else { 165 div.addContent(heading); 166 div.addContent(contentListTree); 167 contentTree.addContent(div); 168 } 169 } 170 171 /** 172 * {@inheritDoc} 173 */ 174 public Content getConstantSummaries() { 175 HtmlTree summariesDiv = new HtmlTree(HtmlTag.DIV); 176 summariesDiv.addStyle(HtmlStyle.constantValuesContainer); 177 return summariesDiv; 178 } 179 180 /** 181 * {@inheritDoc} 182 */ 183 public void addPackageName(PackageElement pkg, Content summariesTree, boolean first) { 184 Content pkgNameContent; 185 if (!first && configuration.allowTag(HtmlTag.SECTION)) { 186 summariesTree.addContent(summaryTree); 187 } 188 if (pkg.isUnnamed()) { 189 summariesTree.addContent(getMarkerAnchor( 190 SectionName.UNNAMED_PACKAGE_ANCHOR)); 191 pkgNameContent = contents.defaultPackageLabel; 192 } else { 193 String parsedPackageName = utils.parsePackageName(pkg); 194 summariesTree.addContent(getMarkerAnchor(parsedPackageName)); 195 pkgNameContent = getPackageLabel(parsedPackageName); 196 } 197 Content headingContent = new StringContent(".*"); 198 Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true, 199 pkgNameContent); 200 heading.addContent(headingContent); 201 if (configuration.allowTag(HtmlTag.SECTION)) { 202 summaryTree = HtmlTree.SECTION(heading); 203 } else { 204 summariesTree.addContent(heading); 205 } 206 } 207 208 /** 209 * {@inheritDoc} 210 */ 211 public Content getClassConstantHeader() { 212 HtmlTree ul = new HtmlTree(HtmlTag.UL); 213 ul.addStyle(HtmlStyle.blockList); 214 return ul; 215 } 216 217 /** 218 * {@inheritDoc} 219 */ 220 public void addClassConstant(Content summariesTree, Content classConstantTree) { 221 if (configuration.allowTag(HtmlTag.SECTION)) { 222 summaryTree.addContent(classConstantTree); 223 } else { 224 summariesTree.addContent(classConstantTree); 225 } 226 } 227 228 /** 229 * Get the table caption and header for the constant summary table 230 * 231 * @param typeElement the TypeElement to be documented 232 * @return constant members header content 233 */ 234 public Content getConstantMembersHeader(TypeElement typeElement) { 235 //generate links backward only to public classes. 236 Content classlink = (utils.isPublic(typeElement) || utils.isProtected(typeElement)) ? 237 getLink(new LinkInfoImpl(configuration, 238 LinkInfoImpl.Kind.CONSTANT_SUMMARY, typeElement)) : 239 new StringContent(utils.getFullyQualifiedName(typeElement)); 240 241 PackageElement enclosingPackage = utils.containingPackage(typeElement); 242 if (!enclosingPackage.isUnnamed()) { 243 Content cb = new ContentBuilder(); 244 cb.addContent(enclosingPackage.getQualifiedName()); 245 cb.addContent("."); 246 cb.addContent(classlink); 247 return getClassName(cb); 248 } else { 249 return getClassName(classlink); 250 } 251 } 252 253 /** 254 * Get the class name in the table caption and the table header. 255 * 256 * @param classStr the class name to print. 257 * @return the table caption and header 258 */ 259 protected Content getClassName(Content classStr) { 260 Content caption = getTableCaption(classStr); 261 Content table = (configuration.isOutputHtml5()) 262 ? HtmlTree.TABLE(HtmlStyle.constantsSummary, caption) 263 : HtmlTree.TABLE(HtmlStyle.constantsSummary, constantsTableSummary, caption); 264 table.addContent(getSummaryTableHeader(constantsTableHeader, "col")); 265 return table; 266 } 267 268 /** 269 * {@inheritDoc} 270 */ 271 public void addConstantMembers(TypeElement typeElement, Collection<VariableElement> fields, 272 Content classConstantTree) { 273 currentTypeElement = typeElement; 274 Content tbody = new HtmlTree(HtmlTag.TBODY); 275 boolean altColor = true; 276 for (VariableElement field : fields) { 277 HtmlTree tr = new HtmlTree(HtmlTag.TR); 278 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor); 279 addConstantMember(field, tr); 280 tbody.addContent(tr); 281 altColor = !altColor; 282 } 283 Content table = getConstantMembersHeader(typeElement); 284 table.addContent(tbody); 285 Content li = HtmlTree.LI(HtmlStyle.blockList, table); 286 classConstantTree.addContent(li); 287 } 288 289 /** 290 * Add the row for the constant summary table. 291 * 292 * @param member the field to be documented. 293 * @param trTree an htmltree object for the table row 294 */ 295 private void addConstantMember(VariableElement member, HtmlTree trTree) { 296 trTree.addContent(getTypeColumn(member)); 297 trTree.addContent(getNameColumn(member)); 298 trTree.addContent(getValue(member)); 299 } 300 301 /** 302 * Get the type column for the constant summary table row. 303 * 304 * @param member the field to be documented. 305 * @return the type column of the constant table row 306 */ 307 private Content getTypeColumn(VariableElement member) { 308 Content anchor = getMarkerAnchor(currentTypeElement.getQualifiedName() + 309 "." + member.getSimpleName()); 310 Content tdType = HtmlTree.TD(HtmlStyle.colFirst, anchor); 311 Content code = new HtmlTree(HtmlTag.CODE); 312 for (Modifier mod : member.getModifiers()) { 313 Content modifier = new StringContent(mod.toString()); 314 code.addContent(modifier); 315 code.addContent(Contents.SPACE); 316 } 317 Content type = getLink(new LinkInfoImpl(configuration, 318 LinkInfoImpl.Kind.CONSTANT_SUMMARY, member.asType())); 319 code.addContent(type); 320 tdType.addContent(code); 321 return tdType; 322 } 323 324 /** 325 * Get the name column for the constant summary table row. 326 * 327 * @param member the field to be documented. 328 * @return the name column of the constant table row 329 */ 330 private Content getNameColumn(VariableElement member) { 331 Content nameContent = getDocLink(LinkInfoImpl.Kind.CONSTANT_SUMMARY, 332 member, member.getSimpleName(), false); 333 Content code = HtmlTree.CODE(nameContent); 334 return HtmlTree.TH_ROW_SCOPE(HtmlStyle.colSecond, code); 335 } 336 337 /** 338 * Get the value column for the constant summary table row. 339 * 340 * @param member the field to be documented. 341 * @return the value column of the constant table row 342 */ 343 private Content getValue(VariableElement member) { 344 String value = utils.constantValueExpresion(member); 345 Content valueContent = new StringContent(value); 346 Content code = HtmlTree.CODE(valueContent); 347 return HtmlTree.TD(HtmlStyle.colLast, code); 348 } 349 350 /** 351 * {@inheritDoc} 352 */ 353 public void addConstantSummaries(Content contentTree, Content summariesTree) { 354 if (configuration.allowTag(HtmlTag.SECTION) && summaryTree != null) { 355 summariesTree.addContent(summaryTree); 356 } 357 if (configuration.allowTag(HtmlTag.MAIN)) { 358 mainTree.addContent(summariesTree); 359 contentTree.addContent(mainTree); 360 } else { 361 contentTree.addContent(summariesTree); 362 } 363 } 364 365 /** 366 * {@inheritDoc} 367 */ 368 public void addFooter(Content contentTree) { 369 Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER)) 370 ? HtmlTree.FOOTER() 371 : contentTree; 372 addNavLinks(false, htmlTree); 373 addBottom(htmlTree); 374 if (configuration.allowTag(HtmlTag.FOOTER)) { 375 contentTree.addContent(htmlTree); 376 } 377 } 378 379 /** 380 * {@inheritDoc} 381 */ 382 @Override 383 public void printDocument(Content contentTree) throws DocFileIOException { 384 printHtmlDocument(null, true, contentTree); 385 } 386} 387