1/* 2 * Copyright (c) 2003, 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.toolkit.builders; 27 28import java.util.Arrays; 29import java.util.List; 30import java.util.Set; 31import java.util.SortedSet; 32 33import javax.lang.model.element.PackageElement; 34import javax.lang.model.element.TypeElement; 35 36import jdk.javadoc.internal.doclets.toolkit.Content; 37import jdk.javadoc.internal.doclets.toolkit.DocletException; 38import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter; 39 40 41/** 42 * Builds the summary for a given package. 43 * 44 * <p><b>This is NOT part of any supported API. 45 * If you write code that depends on this, you do so at your own risk. 46 * This code and its internal interfaces are subject to change or 47 * deletion without notice.</b> 48 * 49 * @author Jamie Ho 50 * @author Bhavesh Patel (Modified) 51 */ 52public class PackageSummaryBuilder extends AbstractBuilder { 53 /** 54 * The root element of the package summary XML is {@value}. 55 */ 56 public static final String ROOT = "PackageDoc"; 57 58 /** 59 * The package being documented. 60 */ 61 private final PackageElement packageElement; 62 63 /** 64 * The doclet specific writer that will output the result. 65 */ 66 private final PackageSummaryWriter packageWriter; 67 68 /** 69 * The content that will be added to the package summary documentation tree. 70 */ 71 private Content contentTree; 72 73 /** 74 * Construct a new PackageSummaryBuilder. 75 * 76 * @param context the build context. 77 * @param pkg the package being documented. 78 * @param packageWriter the doclet specific writer that will output the 79 * result. 80 */ 81 private PackageSummaryBuilder(Context context, 82 PackageElement pkg, 83 PackageSummaryWriter packageWriter) { 84 super(context); 85 this.packageElement = pkg; 86 this.packageWriter = packageWriter; 87 } 88 89 /** 90 * Construct a new PackageSummaryBuilder. 91 * 92 * @param context the build context. 93 * @param pkg the package being documented. 94 * @param packageWriter the doclet specific writer that will output the 95 * result. 96 * 97 * @return an instance of a PackageSummaryBuilder. 98 */ 99 public static PackageSummaryBuilder getInstance(Context context, 100 PackageElement pkg, PackageSummaryWriter packageWriter) { 101 return new PackageSummaryBuilder(context, pkg, packageWriter); 102 } 103 104 /** 105 * Build the package summary. 106 * 107 * @throws DocletException if there is a problem while building the documentation 108 */ 109 @Override 110 public void build() throws DocletException { 111 if (packageWriter == null) { 112 //Doclet does not support this output. 113 return; 114 } 115 build(layoutParser.parseXML(ROOT), contentTree); 116 } 117 118 /** 119 * {@inheritDoc} 120 */ 121 @Override 122 public String getName() { 123 return ROOT; 124 } 125 126 /** 127 * Build the package documentation. 128 * 129 * @param node the XML element that specifies which components to document 130 * @param contentTree the content tree to which the documentation will be added 131 * @throws DocletException if there is a problem while building the documentation 132 */ 133 public void buildPackageDoc(XMLNode node, Content contentTree) throws DocletException { 134 contentTree = packageWriter.getPackageHeader(utils.getPackageName(packageElement)); 135 buildChildren(node, contentTree); 136 packageWriter.addPackageFooter(contentTree); 137 packageWriter.printDocument(contentTree); 138 utils.copyDocFiles(packageElement); 139 } 140 141 /** 142 * Build the content for the package. 143 * 144 * @param node the XML element that specifies which components to document 145 * @param contentTree the content tree to which the package contents 146 * will be added 147 * @throws DocletException if there is a problem while building the documentation 148 */ 149 public void buildContent(XMLNode node, Content contentTree) throws DocletException { 150 Content packageContentTree = packageWriter.getContentHeader(); 151 buildChildren(node, packageContentTree); 152 packageWriter.addPackageContent(contentTree, packageContentTree); 153 } 154 155 /** 156 * Build the package summary. 157 * 158 * @param node the XML element that specifies which components to document 159 * @param packageContentTree the package content tree to which the summaries will 160 * be added 161 * @throws DocletException if there is a problem while building the documentation 162 */ 163 public void buildSummary(XMLNode node, Content packageContentTree) throws DocletException { 164 Content summaryContentTree = packageWriter.getSummaryHeader(); 165 buildChildren(node, summaryContentTree); 166 packageContentTree.addContent(summaryContentTree); 167 } 168 169 /** 170 * Build the summary for the interfaces in this package. 171 * 172 * @param node the XML element that specifies which components to document 173 * @param summaryContentTree the summary tree to which the interface summary 174 * will be added 175 */ 176 public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) { 177 String interfaceTableSummary = 178 configuration.getText("doclet.Member_Table_Summary", 179 configuration.getText("doclet.Interface_Summary"), 180 configuration.getText("doclet.interfaces")); 181 List<String> interfaceTableHeader = Arrays.asList(configuration.getText("doclet.Interface"), 182 configuration.getText("doclet.Description")); 183 184 SortedSet<TypeElement> ilist = utils.isSpecified(packageElement) 185 ? utils.getTypeElementsAsSortedSet(utils.getInterfaces(packageElement)) 186 : configuration.typeElementCatalog.interfaces(packageElement); 187 SortedSet<TypeElement> interfaces = utils.filterOutPrivateClasses(ilist, configuration.javafx); 188 if (!interfaces.isEmpty()) { 189 packageWriter.addClassesSummary(interfaces, 190 configuration.getText("doclet.Interface_Summary"), 191 interfaceTableSummary, interfaceTableHeader, summaryContentTree); 192 } 193 } 194 195 /** 196 * Build the summary for the classes in this package. 197 * 198 * @param node the XML element that specifies which components to document 199 * @param summaryContentTree the summary tree to which the class summary will 200 * be added 201 */ 202 public void buildClassSummary(XMLNode node, Content summaryContentTree) { 203 String classTableSummary = 204 configuration.getText("doclet.Member_Table_Summary", 205 configuration.getText("doclet.Class_Summary"), 206 configuration.getText("doclet.classes")); 207 List<String> classTableHeader = Arrays.asList(configuration.getText("doclet.Class"), 208 configuration.getText("doclet.Description")); 209 SortedSet<TypeElement> clist = utils.isSpecified(packageElement) 210 ? utils.getTypeElementsAsSortedSet(utils.getOrdinaryClasses(packageElement)) 211 : configuration.typeElementCatalog.ordinaryClasses(packageElement); 212 SortedSet<TypeElement> classes = utils.filterOutPrivateClasses(clist, configuration.javafx); 213 if (!classes.isEmpty()) { 214 packageWriter.addClassesSummary(classes, 215 configuration.getText("doclet.Class_Summary"), 216 classTableSummary, classTableHeader, summaryContentTree); 217 } 218 } 219 220 /** 221 * Build the summary for the enums in this package. 222 * 223 * @param node the XML element that specifies which components to document 224 * @param summaryContentTree the summary tree to which the enum summary will 225 * be added 226 */ 227 public void buildEnumSummary(XMLNode node, Content summaryContentTree) { 228 String enumTableSummary = 229 configuration.getText("doclet.Member_Table_Summary", 230 configuration.getText("doclet.Enum_Summary"), 231 configuration.getText("doclet.enums")); 232 List<String> enumTableHeader = Arrays.asList(configuration.getText("doclet.Enum"), 233 configuration.getText("doclet.Description")); 234 SortedSet<TypeElement> elist = utils.isSpecified(packageElement) 235 ? utils.getTypeElementsAsSortedSet(utils.getEnums(packageElement)) 236 : configuration.typeElementCatalog.enums(packageElement); 237 SortedSet<TypeElement> enums = utils.filterOutPrivateClasses(elist, configuration.javafx); 238 if (!enums.isEmpty()) { 239 packageWriter.addClassesSummary(enums, 240 configuration.getText("doclet.Enum_Summary"), 241 enumTableSummary, enumTableHeader, summaryContentTree); 242 } 243 } 244 245 /** 246 * Build the summary for the exceptions in this package. 247 * 248 * @param node the XML element that specifies which components to document 249 * @param summaryContentTree the summary tree to which the exception summary will 250 * be added 251 */ 252 public void buildExceptionSummary(XMLNode node, Content summaryContentTree) { 253 String exceptionTableSummary = 254 configuration.getText("doclet.Member_Table_Summary", 255 configuration.getText("doclet.Exception_Summary"), 256 configuration.getText("doclet.exceptions")); 257 List<String> exceptionTableHeader = Arrays.asList(configuration.getText("doclet.Exception"), 258 configuration.getText("doclet.Description")); 259 Set<TypeElement> iexceptions = 260 utils.isSpecified(packageElement) 261 ? utils.getTypeElementsAsSortedSet(utils.getExceptions(packageElement)) 262 : configuration.typeElementCatalog.exceptions(packageElement); 263 SortedSet<TypeElement> exceptions = utils.filterOutPrivateClasses(iexceptions, 264 configuration.javafx); 265 if (!exceptions.isEmpty()) { 266 packageWriter.addClassesSummary(exceptions, 267 configuration.getText("doclet.Exception_Summary"), 268 exceptionTableSummary, exceptionTableHeader, summaryContentTree); 269 } 270 } 271 272 /** 273 * Build the summary for the errors in this package. 274 * 275 * @param node the XML element that specifies which components to document 276 * @param summaryContentTree the summary tree to which the error summary will 277 * be added 278 */ 279 public void buildErrorSummary(XMLNode node, Content summaryContentTree) { 280 String errorTableSummary = 281 configuration.getText("doclet.Member_Table_Summary", 282 configuration.getText("doclet.Error_Summary"), 283 configuration.getText("doclet.errors")); 284 List<String> errorTableHeader = Arrays.asList(configuration.getText("doclet.Error"), 285 configuration.getText("doclet.Description")); 286 Set<TypeElement> ierrors = 287 utils.isSpecified(packageElement) 288 ? utils.getTypeElementsAsSortedSet(utils.getErrors(packageElement)) 289 : configuration.typeElementCatalog.errors(packageElement); 290 SortedSet<TypeElement> errors = utils.filterOutPrivateClasses(ierrors, configuration.javafx); 291 if (!errors.isEmpty()) { 292 packageWriter.addClassesSummary(errors, 293 configuration.getText("doclet.Error_Summary"), 294 errorTableSummary, errorTableHeader, summaryContentTree); 295 } 296 } 297 298 /** 299 * Build the summary for the annotation type in this package. 300 * 301 * @param node the XML element that specifies which components to document 302 * @param summaryContentTree the summary tree to which the annotation type 303 * summary will be added 304 */ 305 public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) { 306 String annotationtypeTableSummary = 307 configuration.getText("doclet.Member_Table_Summary", 308 configuration.getText("doclet.Annotation_Types_Summary"), 309 configuration.getText("doclet.annotationtypes")); 310 List<String> annotationtypeTableHeader = Arrays.asList( 311 configuration.getText("doclet.AnnotationType"), 312 configuration.getText("doclet.Description")); 313 SortedSet<TypeElement> iannotationTypes = 314 utils.isSpecified(packageElement) 315 ? utils.getTypeElementsAsSortedSet(utils.getAnnotationTypes(packageElement)) 316 : configuration.typeElementCatalog.annotationTypes(packageElement); 317 SortedSet<TypeElement> annotationTypes = utils.filterOutPrivateClasses(iannotationTypes, 318 configuration.javafx); 319 if (!annotationTypes.isEmpty()) { 320 packageWriter.addClassesSummary(annotationTypes, 321 configuration.getText("doclet.Annotation_Types_Summary"), 322 annotationtypeTableSummary, annotationtypeTableHeader, 323 summaryContentTree); 324 } 325 } 326 327 /** 328 * Build the description of the summary. 329 * 330 * @param node the XML element that specifies which components to document 331 * @param packageContentTree the tree to which the package description will 332 * be added 333 */ 334 public void buildPackageDescription(XMLNode node, Content packageContentTree) { 335 if (configuration.nocomment) { 336 return; 337 } 338 packageWriter.addPackageDescription(packageContentTree); 339 } 340 341 /** 342 * Build the tags of the summary. 343 * 344 * @param node the XML element that specifies which components to document 345 * @param packageContentTree the tree to which the package tags will be added 346 */ 347 public void buildPackageTags(XMLNode node, Content packageContentTree) { 348 if (configuration.nocomment) { 349 return; 350 } 351 packageWriter.addPackageTags(packageContentTree); 352 } 353} 354