1 /* 2 * Copyright (c) 2003, 2019, 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 26 package jdk.javadoc.internal.doclets.toolkit.builders; 27 28 import java.util.Set; 29 import java.util.SortedSet; 30 31 import javax.lang.model.element.PackageElement; 32 import javax.lang.model.element.TypeElement; 33 34 import jdk.javadoc.internal.doclets.toolkit.Content; 35 import jdk.javadoc.internal.doclets.toolkit.DocFilesHandler; 36 import jdk.javadoc.internal.doclets.toolkit.DocletException; 37 import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter; 38 39 40 /** 41 * Builds the summary for a given package. 42 * 43 * <p><b>This is NOT part of any supported API. 44 * If you write code that depends on this, you do so at your own risk. 45 * This code and its internal interfaces are subject to change or 46 * deletion without notice.</b> 47 * 48 * @author Jamie Ho 49 * @author Bhavesh Patel (Modified) 50 */ 51 public class PackageSummaryBuilder extends AbstractBuilder { 52 53 /** 54 * The package being documented. 55 */ 56 private final PackageElement packageElement; 57 58 /** 59 * The doclet specific writer that will output the result. 60 */ 61 private final PackageSummaryWriter packageWriter; 62 63 /** 64 * The content that will be added to the package summary documentation tree. 65 */ 66 private Content contentTree; 67 68 /** 69 * Construct a new PackageSummaryBuilder. 70 * 71 * @param context the build context. 72 * @param pkg the package being documented. 73 * @param packageWriter the doclet specific writer that will output the 74 * result. 75 */ 76 private PackageSummaryBuilder(Context context, 77 PackageElement pkg, 78 PackageSummaryWriter packageWriter) { 79 super(context); 80 this.packageElement = pkg; 81 this.packageWriter = packageWriter; 82 } 83 84 /** 85 * Construct a new PackageSummaryBuilder. 86 * 87 * @param context the build context. 88 * @param pkg the package being documented. 89 * @param packageWriter the doclet specific writer that will output the 90 * result. 91 * 92 * @return an instance of a PackageSummaryBuilder. 93 */ 94 public static PackageSummaryBuilder getInstance(Context context, 95 PackageElement pkg, PackageSummaryWriter packageWriter) { 96 return new PackageSummaryBuilder(context, pkg, packageWriter); 97 } 98 99 /** 100 * Build the package summary. 101 * 102 * @throws DocletException if there is a problem while building the documentation 103 */ 104 @Override 105 public void build() throws DocletException { 106 if (packageWriter == null) { 107 //Doclet does not support this output. 108 return; 109 } 110 buildPackageDoc(contentTree); 111 } 112 113 /** 114 * Build the package documentation. 115 * 116 * @param contentTree the content tree to which the documentation will be added 117 * @throws DocletException if there is a problem while building the documentation 118 */ 119 protected void buildPackageDoc(Content contentTree) throws DocletException { 120 contentTree = packageWriter.getPackageHeader(utils.getPackageName(packageElement)); 121 122 buildContent(contentTree); 123 124 packageWriter.addPackageFooter(contentTree); 125 packageWriter.printDocument(contentTree); 126 DocFilesHandler docFilesHandler = configuration 127 .getWriterFactory() 128 .getDocFilesHandler(packageElement); 129 docFilesHandler.copyDocFiles(); 130 } 131 132 /** 133 * Build the content for the package. 134 * 135 * @param contentTree the content tree to which the package contents 136 * will be added 137 * @throws DocletException if there is a problem while building the documentation 138 */ 139 protected void buildContent(Content contentTree) throws DocletException { 140 Content packageContentTree = packageWriter.getContentHeader(); 141 142 buildPackageDescription(packageContentTree); 143 buildPackageTags(packageContentTree); 144 buildSummary(packageContentTree); 145 146 packageWriter.addPackageContent(contentTree, packageContentTree); 147 } 148 149 /** 150 * Build the package summary. 151 * 152 * @param packageContentTree the package content tree to which the summaries will 153 * be added 154 * @throws DocletException if there is a problem while building the documentation 155 */ 156 protected void buildSummary(Content packageContentTree) throws DocletException { 157 Content summaryContentTree = packageWriter.getSummaryHeader(); 158 159 buildInterfaceSummary(summaryContentTree); 160 buildClassSummary(summaryContentTree); 161 buildEnumSummary(summaryContentTree); 162 buildExceptionSummary(summaryContentTree); 163 buildErrorSummary(summaryContentTree); 164 buildAnnotationTypeSummary(summaryContentTree); 165 166 packageContentTree.add(packageWriter.getPackageSummary(summaryContentTree)); 167 } 168 169 /** 170 * Build the summary for the interfaces in this package. 171 * 172 * @param summaryContentTree the summary tree to which the interface summary 173 * will be added 174 */ 175 protected void buildInterfaceSummary(Content summaryContentTree) { 176 SortedSet<TypeElement> ilist = utils.isSpecified(packageElement) 177 ? utils.getTypeElementsAsSortedSet(utils.getInterfaces(packageElement)) 178 : configuration.typeElementCatalog.interfaces(packageElement); 179 SortedSet<TypeElement> interfaces = utils.filterOutPrivateClasses(ilist, configuration.javafx); 180 if (!interfaces.isEmpty()) { 181 packageWriter.addInterfaceSummary(interfaces, summaryContentTree); 182 } 183 } 184 185 /** 186 * Build the summary for the classes in this package. 187 * 188 * @param summaryContentTree the summary tree to which the class summary will 189 * be added 190 */ 191 protected void buildClassSummary(Content summaryContentTree) { 192 SortedSet<TypeElement> clist = utils.isSpecified(packageElement) 193 ? utils.getTypeElementsAsSortedSet(utils.getOrdinaryClasses(packageElement)) 194 : configuration.typeElementCatalog.ordinaryClasses(packageElement); 195 SortedSet<TypeElement> classes = utils.filterOutPrivateClasses(clist, configuration.javafx); 196 if (!classes.isEmpty()) { 197 packageWriter.addClassSummary(classes, summaryContentTree); 198 } 199 } 200 201 /** 202 * Build the summary for the enums in this package. 203 * 204 * @param summaryContentTree the summary tree to which the enum summary will 205 * be added 206 */ 207 protected void buildEnumSummary(Content summaryContentTree) { 208 SortedSet<TypeElement> elist = utils.isSpecified(packageElement) 209 ? utils.getTypeElementsAsSortedSet(utils.getEnums(packageElement)) 210 : configuration.typeElementCatalog.enums(packageElement); 211 SortedSet<TypeElement> enums = utils.filterOutPrivateClasses(elist, configuration.javafx); 212 if (!enums.isEmpty()) { 213 packageWriter.addEnumSummary(enums, summaryContentTree); 214 } 215 } 216 217 /** 218 * Build the summary for the exceptions in this package. 219 * 220 * @param summaryContentTree the summary tree to which the exception summary will 221 * be added 222 */ 223 protected void buildExceptionSummary(Content summaryContentTree) { 224 Set<TypeElement> iexceptions = 225 utils.isSpecified(packageElement) 226 ? utils.getTypeElementsAsSortedSet(utils.getExceptions(packageElement)) 227 : configuration.typeElementCatalog.exceptions(packageElement); 228 SortedSet<TypeElement> exceptions = utils.filterOutPrivateClasses(iexceptions, 229 configuration.javafx); 230 if (!exceptions.isEmpty()) { 231 packageWriter.addExceptionSummary(exceptions, summaryContentTree); 232 } 233 } 234 235 /** 236 * Build the summary for the errors in this package. 237 * 238 * @param summaryContentTree the summary tree to which the error summary will 239 * be added 240 */ 241 protected void buildErrorSummary(Content summaryContentTree) { 242 Set<TypeElement> ierrors = 243 utils.isSpecified(packageElement) 244 ? utils.getTypeElementsAsSortedSet(utils.getErrors(packageElement)) 245 : configuration.typeElementCatalog.errors(packageElement); 246 SortedSet<TypeElement> errors = utils.filterOutPrivateClasses(ierrors, configuration.javafx); 247 if (!errors.isEmpty()) { 248 packageWriter.addErrorSummary(errors, summaryContentTree); 249 } 250 } 251 252 /** 253 * Build the summary for the annotation type in this package. 254 * 255 * @param summaryContentTree the summary tree to which the annotation type 256 * summary will be added 257 */ 258 protected void buildAnnotationTypeSummary(Content summaryContentTree) { 259 SortedSet<TypeElement> iannotationTypes = 260 utils.isSpecified(packageElement) 261 ? utils.getTypeElementsAsSortedSet(utils.getAnnotationTypes(packageElement)) 262 : configuration.typeElementCatalog.annotationTypes(packageElement); 263 SortedSet<TypeElement> annotationTypes = utils.filterOutPrivateClasses(iannotationTypes, 264 configuration.javafx); 265 if (!annotationTypes.isEmpty()) { 266 packageWriter.addAnnotationTypeSummary(annotationTypes, summaryContentTree); 267 } 268 } 269 270 /** 271 * Build the description of the summary. 272 * 273 * @param packageContentTree the tree to which the package description will 274 * be added 275 */ 276 protected void buildPackageDescription(Content packageContentTree) { 277 if (configuration.nocomment) { 278 return; 279 } 280 packageWriter.addPackageDescription(packageContentTree); 281 } 282 283 /** 284 * Build the tags of the summary. 285 * 286 * @param packageContentTree the tree to which the package tags will be added 287 */ 288 protected void buildPackageTags(Content packageContentTree) { 289 if (configuration.nocomment) { 290 return; 291 } 292 packageWriter.addPackageTags(packageContentTree); 293 } 294 }