PackageWriterImpl.java revision 3294:9adfb22ff08f
191094Sdes/* 2115619Sdes * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved. 3228690Sdes * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 491094Sdes * 591094Sdes * This code is free software; you can redistribute it and/or modify it 691094Sdes * under the terms of the GNU General Public License version 2 only, as 799158Sdes * published by the Free Software Foundation. Oracle designates this 899158Sdes * particular file as subject to the "Classpath" exception as provided 999158Sdes * by Oracle in the LICENSE file that accompanied this code. 1091094Sdes * 1191094Sdes * This code is distributed in the hope that it will be useful, but WITHOUT 1291094Sdes * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1391094Sdes * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1491094Sdes * version 2 for more details (a copy is included in the LICENSE file that 1591094Sdes * accompanied this code). 1691094Sdes * 1791094Sdes * You should have received a copy of the GNU General Public License version 1891094Sdes * 2 along with this work; if not, write to the Free Software Foundation, 1991094Sdes * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2091094Sdes * 2191094Sdes * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2291094Sdes * or visit www.oracle.com if you need additional information or have any 2391094Sdes * questions. 2491094Sdes */ 2591094Sdes 2691094Sdespackage jdk.javadoc.internal.doclets.formats.html; 2791094Sdes 2891094Sdesimport java.io.*; 2991094Sdesimport java.util.*; 3091094Sdes 3191094Sdesimport javax.lang.model.element.ModuleElement; 3291094Sdesimport javax.lang.model.element.PackageElement; 3391094Sdesimport javax.lang.model.element.TypeElement; 3491094Sdes 35263421Sdesimport com.sun.source.doctree.DocTree; 3691094Sdesimport jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; 3791094Sdesimport jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 38228690Sdesimport jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 39228690Sdesimport jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 40228690Sdesimport jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; 41228690Sdesimport jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 4291094Sdesimport jdk.javadoc.internal.doclets.toolkit.Content; 4391094Sdesimport jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter; 4491094Sdesimport jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; 4591094Sdesimport jdk.javadoc.internal.doclets.toolkit.util.DocPath; 4691094Sdesimport jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 4791094Sdes 4891094Sdes/** 4991094Sdes * Class to generate file for each package contents in the right-hand 5091094Sdes * frame. This will list all the Class Kinds in the package. A click on any 5191094Sdes * class-kind will update the frame with the clicked class-kind page. 5291094Sdes * 5391094Sdes * <p><b>This is NOT part of any supported API. 5491094Sdes * If you write code that depends on this, you do so at your own risk. 5591094Sdes * This code and its internal interfaces are subject to change or 56174832Sdes * deletion without notice.</b> 5791094Sdes * 5891094Sdes * @author Atul M Dambalkar 5991094Sdes * @author Bhavesh Patel (Modified) 6091094Sdes */ 61107937Sdespublic class PackageWriterImpl extends HtmlDocletWriter 6291094Sdes implements PackageSummaryWriter { 6391094Sdes 6491094Sdes /** 6591094Sdes * The prev package name in the alpha-order list. 6691094Sdes */ 6791094Sdes protected PackageElement prev; 6891094Sdes 6991100Sdes /** 7091094Sdes * The next package name in the alpha-order list. 7191094Sdes */ 7291094Sdes protected PackageElement next; 7391094Sdes 7491094Sdes /** 7591094Sdes * The package being documented. 7691094Sdes */ 7791094Sdes protected PackageElement packageElement; 7891094Sdes 7991094Sdes /** 8091094Sdes * The HTML tree for main tag. 8191094Sdes */ 8291094Sdes protected HtmlTree mainTree = HtmlTree.MAIN(); 8391094Sdes 8491094Sdes /** 8591094Sdes * The HTML tree for section tag. 8691094Sdes */ 8791094Sdes protected HtmlTree sectionTree = HtmlTree.SECTION(); 8891094Sdes 8991094Sdes /** 9091094Sdes * Constructor to construct PackageWriter object and to generate 9191094Sdes * "package-summary.html" file in the respective package directory. 9291094Sdes * For example for package "java.lang" this will generate file 9391094Sdes * "package-summary.html" file in the "java/lang" directory. It will also 9491094Sdes * create "java/lang" directory in the current or the destination directory 9591094Sdes * if it doesn't exist. 9691094Sdes * 9791094Sdes * @param configuration the configuration of the doclet. 9891094Sdes * @param packageElement PackageElement under consideration. 99141098Sdes * @param prev Previous package in the sorted array. 10091094Sdes * @param next Next package in the sorted array. 10191094Sdes */ 10291094Sdes public PackageWriterImpl(ConfigurationImpl configuration, 10391094Sdes PackageElement packageElement, PackageElement prev, PackageElement next) 10491094Sdes throws IOException { 10591094Sdes super(configuration, DocPath 10691094Sdes .forPackage(packageElement) 10791094Sdes .resolve(DocPaths.PACKAGE_SUMMARY)); 10891094Sdes this.prev = prev; 10991094Sdes this.next = next; 11091094Sdes this.packageElement = packageElement; 11191100Sdes } 11291094Sdes 11391094Sdes /** 11491094Sdes * {@inheritDoc} 11591094Sdes */ 11691094Sdes public Content getPackageHeader(String heading) { 11791094Sdes HtmlTree bodyTree = getBody(true, getWindowTitle(utils.getPackageName(packageElement))); 11891094Sdes HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) 11991094Sdes ? HtmlTree.HEADER() 12091094Sdes : bodyTree; 12191094Sdes addTop(htmlTree); 12291094Sdes addNavLinks(true, htmlTree); 12391094Sdes if (configuration.allowTag(HtmlTag.HEADER)) { 12491094Sdes bodyTree.addContent(htmlTree); 12591094Sdes } 12691094Sdes HtmlTree div = new HtmlTree(HtmlTag.DIV); 12791094Sdes div.addStyle(HtmlStyle.header); 12891094Sdes ModuleElement mdle = configuration.root.getElementUtils().getModuleOf(packageElement); 12991100Sdes if (mdle != null && !mdle.isUnnamed()) { 13091100Sdes Content classModuleLabel = HtmlTree.SPAN(HtmlStyle.moduleLabelInClass, moduleLabel); 13191100Sdes Content moduleNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, classModuleLabel); 13291100Sdes moduleNameDiv.addContent(getSpace()); 13391100Sdes moduleNameDiv.addContent(getModuleLink(mdle, 134228690Sdes new StringContent(mdle.getQualifiedName().toString()))); 135228690Sdes div.addContent(moduleNameDiv); 136228690Sdes } 13791100Sdes Content annotationContent = new HtmlTree(HtmlTag.P); 138 addAnnotationInfo(packageElement, annotationContent); 139 div.addContent(annotationContent); 140 Content tHeading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true, 141 HtmlStyle.title, packageLabel); 142 tHeading.addContent(getSpace()); 143 Content packageHead = new StringContent(heading); 144 tHeading.addContent(packageHead); 145 div.addContent(tHeading); 146 addDeprecationInfo(div); 147 if (!utils.getBody(packageElement).isEmpty() && !configuration.nocomment) { 148 HtmlTree docSummaryDiv = new HtmlTree(HtmlTag.DIV); 149 docSummaryDiv.addStyle(HtmlStyle.docSummary); 150 addSummaryComment(packageElement, docSummaryDiv); 151 div.addContent(docSummaryDiv); 152 Content space = getSpace(); 153 Content descLink = getHyperLink(getDocLink( 154 SectionName.PACKAGE_DESCRIPTION), 155 descriptionLabel, "", ""); 156 Content descPara = new HtmlTree(HtmlTag.P, seeLabel, space, descLink); 157 div.addContent(descPara); 158 } 159 if (configuration.allowTag(HtmlTag.MAIN)) { 160 mainTree.addContent(div); 161 } else { 162 bodyTree.addContent(div); 163 } 164 return bodyTree; 165 } 166 167 /** 168 * {@inheritDoc} 169 */ 170 public Content getContentHeader() { 171 HtmlTree div = new HtmlTree(HtmlTag.DIV); 172 div.addStyle(HtmlStyle.contentContainer); 173 return div; 174 } 175 176 /** 177 * Add the package deprecation information to the documentation tree. 178 * 179 * @param div the content tree to which the deprecation information will be added 180 */ 181 public void addDeprecationInfo(Content div) { 182 List<? extends DocTree> deprs = utils.getBlockTags(packageElement, DocTree.Kind.DEPRECATED); 183 if (utils.isDeprecated(packageElement)) { 184 CommentHelper ch = utils.getCommentHelper(packageElement); 185 HtmlTree deprDiv = new HtmlTree(HtmlTag.DIV); 186 deprDiv.addStyle(HtmlStyle.deprecatedContent); 187 Content deprPhrase = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase); 188 deprDiv.addContent(deprPhrase); 189 if (!deprs.isEmpty()) { 190 List<? extends DocTree> commentTags = ch.getDescription(configuration, deprs.get(0)); 191 if (!commentTags.isEmpty()) { 192 addInlineDeprecatedComment(packageElement, deprs.get(0), deprDiv); 193 } 194 } 195 div.addContent(deprDiv); 196 } 197 } 198 199 /** 200 * {@inheritDoc} 201 */ 202 public Content getSummaryHeader() { 203 HtmlTree ul = new HtmlTree(HtmlTag.UL); 204 ul.addStyle(HtmlStyle.blockList); 205 return ul; 206 } 207 208 /** 209 * {@inheritDoc} 210 */ 211 public void addClassesSummary(SortedSet<TypeElement> classes, String label, 212 String tableSummary, List<String> tableHeader, Content summaryContentTree) { 213 if(!classes.isEmpty()) { 214 Content caption = getTableCaption(new RawHtml(label)); 215 Content table = (configuration.isOutputHtml5()) 216 ? HtmlTree.TABLE(HtmlStyle.typeSummary, caption) 217 : HtmlTree.TABLE(HtmlStyle.typeSummary, tableSummary, caption); 218 table.addContent(getSummaryTableHeader(tableHeader, "col")); 219 Content tbody = new HtmlTree(HtmlTag.TBODY); 220 boolean altColor = false; 221 for (TypeElement klass : classes) { 222 altColor = !altColor; 223 if (!utils.isCoreClass(klass) || 224 !configuration.isGeneratedDoc(klass)) { 225 continue; 226 } 227 Content classContent = getLink(new LinkInfoImpl( 228 configuration, LinkInfoImpl.Kind.PACKAGE, klass)); 229 Content tdClass = HtmlTree.TD(HtmlStyle.colFirst, classContent); 230 HtmlTree tr = HtmlTree.TR(tdClass); 231 tr.addStyle(altColor ? HtmlStyle.altColor : HtmlStyle.rowColor); 232 233 HtmlTree tdClassDescription = new HtmlTree(HtmlTag.TD); 234 tdClassDescription.addStyle(HtmlStyle.colLast); 235 if (utils.isDeprecated(klass)) { 236 tdClassDescription.addContent(deprecatedLabel); 237 List<? extends DocTree> tags = utils.getDeprecatedTrees(klass); 238 if (!tags.isEmpty()) { 239 addSummaryDeprecatedComment(klass, tags.get(0), tdClassDescription); 240 } 241 } else { 242 addSummaryComment(klass, tdClassDescription); 243 } 244 tr.addContent(tdClassDescription); 245 tbody.addContent(tr); 246 } 247 table.addContent(tbody); 248 Content li = HtmlTree.LI(HtmlStyle.blockList, table); 249 summaryContentTree.addContent(li); 250 } 251 } 252 253 /** 254 * {@inheritDoc} 255 */ 256 public void addPackageDescription(Content packageContentTree) { 257 if (!utils.getBody(packageElement).isEmpty()) { 258 packageContentTree.addContent( 259 getMarkerAnchor(SectionName.PACKAGE_DESCRIPTION)); 260 Content h2Content = new StringContent( 261 configuration.getText("doclet.Package_Description", 262 packageElement.isUnnamed() ? "" : utils.getPackageName(packageElement))); 263 Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true, h2Content); 264 if (configuration.allowTag(HtmlTag.SECTION)) { 265 sectionTree.addContent(heading); 266 addInlineComment(packageElement, sectionTree); 267 } else { 268 packageContentTree.addContent(heading); 269 addInlineComment(packageElement, packageContentTree); 270 } 271 } 272 } 273 274 /** 275 * {@inheritDoc} 276 */ 277 public void addPackageTags(Content packageContentTree) { 278 Content htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 279 ? sectionTree 280 : packageContentTree; 281 addTagsInfo(packageElement, htmlTree); 282 } 283 284 /** 285 * {@inheritDoc} 286 */ 287 public void addPackageContent(Content contentTree, Content packageContentTree) { 288 if (configuration.allowTag(HtmlTag.MAIN)) { 289 packageContentTree.addContent(sectionTree); 290 mainTree.addContent(packageContentTree); 291 contentTree.addContent(mainTree); 292 } else { 293 contentTree.addContent(packageContentTree); 294 } 295 } 296 297 /** 298 * {@inheritDoc} 299 */ 300 public void addPackageFooter(Content contentTree) { 301 Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER)) 302 ? HtmlTree.FOOTER() 303 : contentTree; 304 addNavLinks(false, htmlTree); 305 addBottom(htmlTree); 306 if (configuration.allowTag(HtmlTag.FOOTER)) { 307 contentTree.addContent(htmlTree); 308 } 309 } 310 311 /** 312 * {@inheritDoc} 313 */ 314 public void printDocument(Content contentTree) throws IOException { 315 printHtmlDocument(configuration.metakeywords.getMetaKeywords(packageElement), 316 true, contentTree); 317 } 318 319 /** 320 * Get "Use" link for this pacakge in the navigation bar. 321 * 322 * @return a content tree for the class use link 323 */ 324 protected Content getNavLinkClassUse() { 325 Content useLink = getHyperLink(DocPaths.PACKAGE_USE, 326 useLabel, "", ""); 327 Content li = HtmlTree.LI(useLink); 328 return li; 329 } 330 331 /** 332 * Get "PREV PACKAGE" link in the navigation bar. 333 * 334 * @return a content tree for the previous link 335 */ 336 public Content getNavLinkPrevious() { 337 Content li; 338 if (prev == null) { 339 li = HtmlTree.LI(prevpackageLabel); 340 } else { 341 DocPath path = DocPath.relativePath(packageElement, prev); 342 li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.PACKAGE_SUMMARY), 343 prevpackageLabel, "", "")); 344 } 345 return li; 346 } 347 348 /** 349 * Get "NEXT PACKAGE" link in the navigation bar. 350 * 351 * @return a content tree for the next link 352 */ 353 public Content getNavLinkNext() { 354 Content li; 355 if (next == null) { 356 li = HtmlTree.LI(nextpackageLabel); 357 } else { 358 DocPath path = DocPath.relativePath(packageElement, next); 359 li = HtmlTree.LI(getHyperLink(path.resolve(DocPaths.PACKAGE_SUMMARY), 360 nextpackageLabel, "", "")); 361 } 362 return li; 363 } 364 365 /** 366 * Get "Tree" link in the navigation bar. This will be link to the package 367 * tree file. 368 * 369 * @return a content tree for the tree link 370 */ 371 protected Content getNavLinkTree() { 372 Content useLink = getHyperLink(DocPaths.PACKAGE_TREE, 373 treeLabel, "", ""); 374 Content li = HtmlTree.LI(useLink); 375 return li; 376 } 377 378 /** 379 * Highlight "Package" in the navigation bar, as this is the package page. 380 * 381 * @return a content tree for the package link 382 */ 383 protected Content getNavLinkPackage() { 384 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, packageLabel); 385 return li; 386 } 387} 388