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