1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/ProfilePackageSummaryBuilder.java Wed Apr 27 01:34:52 2016 +0800 1.3 @@ -0,0 +1,374 @@ 1.4 +/* 1.5 + * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package com.sun.tools.doclets.internal.toolkit.builders; 1.30 + 1.31 +import java.io.*; 1.32 + 1.33 +import com.sun.javadoc.*; 1.34 +import com.sun.tools.javac.jvm.Profile; 1.35 +import com.sun.tools.doclets.internal.toolkit.*; 1.36 +import com.sun.tools.doclets.internal.toolkit.util.*; 1.37 + 1.38 +/** 1.39 + * Builds the summary for a given profile package. 1.40 + * 1.41 + * <p><b>This is NOT part of any supported API. 1.42 + * If you write code that depends on this, you do so at your own risk. 1.43 + * This code and its internal interfaces are subject to change or 1.44 + * deletion without notice.</b> 1.45 + * 1.46 + * @author Bhavesh Patel 1.47 + */ 1.48 +public class ProfilePackageSummaryBuilder extends AbstractBuilder { 1.49 + /** 1.50 + * The root element of the profile package summary XML is {@value}. 1.51 + */ 1.52 + public static final String ROOT = "PackageDoc"; 1.53 + 1.54 + /** 1.55 + * The profile package being documented. 1.56 + */ 1.57 + private final PackageDoc packageDoc; 1.58 + 1.59 + /** 1.60 + * The name of the profile being documented. 1.61 + */ 1.62 + private final String profileName; 1.63 + 1.64 + /** 1.65 + * The value of the profile being documented. 1.66 + */ 1.67 + private final int profileValue; 1.68 + 1.69 + /** 1.70 + * The doclet specific writer that will output the result. 1.71 + */ 1.72 + private final ProfilePackageSummaryWriter profilePackageWriter; 1.73 + 1.74 + /** 1.75 + * The content that will be added to the profile package summary documentation tree. 1.76 + */ 1.77 + private Content contentTree; 1.78 + 1.79 + /** 1.80 + * Construct a new ProfilePackageSummaryBuilder. 1.81 + * 1.82 + * @param context the build context. 1.83 + * @param pkg the profile package being documented. 1.84 + * @param profilePackageWriter the doclet specific writer that will output the 1.85 + * result. 1.86 + * @param profile the profile being documented. 1.87 + */ 1.88 + private ProfilePackageSummaryBuilder(Context context, 1.89 + PackageDoc pkg, ProfilePackageSummaryWriter profilePackageWriter, 1.90 + Profile profile) { 1.91 + super(context); 1.92 + this.packageDoc = pkg; 1.93 + this.profilePackageWriter = profilePackageWriter; 1.94 + this.profileName = profile.name; 1.95 + this.profileValue = profile.value; 1.96 + } 1.97 + 1.98 + /** 1.99 + * Construct a new ProfilePackageSummaryBuilder. 1.100 + * 1.101 + * @param context the build context. 1.102 + * @param pkg the profile package being documented. 1.103 + * @param profilePackageWriter the doclet specific writer that will output the 1.104 + * result. 1.105 + * @param profile the profile being documented. 1.106 + * 1.107 + * @return an instance of a ProfilePackageSummaryBuilder. 1.108 + */ 1.109 + public static ProfilePackageSummaryBuilder getInstance(Context context, 1.110 + PackageDoc pkg, ProfilePackageSummaryWriter profilePackageWriter, 1.111 + Profile profile) { 1.112 + return new ProfilePackageSummaryBuilder(context, pkg, profilePackageWriter, 1.113 + profile); 1.114 + } 1.115 + 1.116 + /** 1.117 + * Build the profile package summary. 1.118 + */ 1.119 + public void build() throws IOException { 1.120 + if (profilePackageWriter == null) { 1.121 + //Doclet does not support this output. 1.122 + return; 1.123 + } 1.124 + build(layoutParser.parseXML(ROOT), contentTree); 1.125 + } 1.126 + 1.127 + /** 1.128 + * {@inheritDoc} 1.129 + */ 1.130 + public String getName() { 1.131 + return ROOT; 1.132 + } 1.133 + 1.134 + /** 1.135 + * Build the profile package documentation. 1.136 + * 1.137 + * @param node the XML element that specifies which components to document 1.138 + * @param contentTree the content tree to which the documentation will be added 1.139 + */ 1.140 + public void buildPackageDoc(XMLNode node, Content contentTree) throws Exception { 1.141 + contentTree = profilePackageWriter.getPackageHeader( 1.142 + Util.getPackageName(packageDoc)); 1.143 + buildChildren(node, contentTree); 1.144 + profilePackageWriter.addPackageFooter(contentTree); 1.145 + profilePackageWriter.printDocument(contentTree); 1.146 + profilePackageWriter.close(); 1.147 + Util.copyDocFiles(configuration, packageDoc); 1.148 + } 1.149 + 1.150 + /** 1.151 + * Build the content for the profile package doc. 1.152 + * 1.153 + * @param node the XML element that specifies which components to document 1.154 + * @param contentTree the content tree to which the package contents 1.155 + * will be added 1.156 + */ 1.157 + public void buildContent(XMLNode node, Content contentTree) { 1.158 + Content packageContentTree = profilePackageWriter.getContentHeader(); 1.159 + buildChildren(node, packageContentTree); 1.160 + contentTree.addContent(packageContentTree); 1.161 + } 1.162 + 1.163 + /** 1.164 + * Build the profile package summary. 1.165 + * 1.166 + * @param node the XML element that specifies which components to document 1.167 + * @param packageContentTree the package content tree to which the summaries will 1.168 + * be added 1.169 + */ 1.170 + public void buildSummary(XMLNode node, Content packageContentTree) { 1.171 + Content summaryContentTree = profilePackageWriter.getSummaryHeader(); 1.172 + buildChildren(node, summaryContentTree); 1.173 + packageContentTree.addContent(summaryContentTree); 1.174 + } 1.175 + 1.176 + /** 1.177 + * Build the summary for the interfaces in this package. 1.178 + * 1.179 + * @param node the XML element that specifies which components to document 1.180 + * @param summaryContentTree the summary tree to which the interface summary 1.181 + * will be added 1.182 + */ 1.183 + public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) { 1.184 + String interfaceTableSummary = 1.185 + configuration.getText("doclet.Member_Table_Summary", 1.186 + configuration.getText("doclet.Interface_Summary"), 1.187 + configuration.getText("doclet.interfaces")); 1.188 + String[] interfaceTableHeader = new String[] { 1.189 + configuration.getText("doclet.Interface"), 1.190 + configuration.getText("doclet.Description") 1.191 + }; 1.192 + ClassDoc[] interfaces = 1.193 + packageDoc.isIncluded() 1.194 + ? packageDoc.interfaces() 1.195 + : configuration.classDocCatalog.interfaces( 1.196 + Util.getPackageName(packageDoc)); 1.197 + if (interfaces.length > 0) { 1.198 + profilePackageWriter.addClassesSummary( 1.199 + interfaces, 1.200 + configuration.getText("doclet.Interface_Summary"), 1.201 + interfaceTableSummary, interfaceTableHeader, summaryContentTree); 1.202 + } 1.203 + } 1.204 + 1.205 + /** 1.206 + * Build the summary for the classes in this package. 1.207 + * 1.208 + * @param node the XML element that specifies which components to document 1.209 + * @param summaryContentTree the summary tree to which the class summary will 1.210 + * be added 1.211 + */ 1.212 + public void buildClassSummary(XMLNode node, Content summaryContentTree) { 1.213 + String classTableSummary = 1.214 + configuration.getText("doclet.Member_Table_Summary", 1.215 + configuration.getText("doclet.Class_Summary"), 1.216 + configuration.getText("doclet.classes")); 1.217 + String[] classTableHeader = new String[] { 1.218 + configuration.getText("doclet.Class"), 1.219 + configuration.getText("doclet.Description") 1.220 + }; 1.221 + ClassDoc[] classes = 1.222 + packageDoc.isIncluded() 1.223 + ? packageDoc.ordinaryClasses() 1.224 + : configuration.classDocCatalog.ordinaryClasses( 1.225 + Util.getPackageName(packageDoc)); 1.226 + if (classes.length > 0) { 1.227 + profilePackageWriter.addClassesSummary( 1.228 + classes, 1.229 + configuration.getText("doclet.Class_Summary"), 1.230 + classTableSummary, classTableHeader, summaryContentTree); 1.231 + } 1.232 + } 1.233 + 1.234 + /** 1.235 + * Build the summary for the enums in this package. 1.236 + * 1.237 + * @param node the XML element that specifies which components to document 1.238 + * @param summaryContentTree the summary tree to which the enum summary will 1.239 + * be added 1.240 + */ 1.241 + public void buildEnumSummary(XMLNode node, Content summaryContentTree) { 1.242 + String enumTableSummary = 1.243 + configuration.getText("doclet.Member_Table_Summary", 1.244 + configuration.getText("doclet.Enum_Summary"), 1.245 + configuration.getText("doclet.enums")); 1.246 + String[] enumTableHeader = new String[] { 1.247 + configuration.getText("doclet.Enum"), 1.248 + configuration.getText("doclet.Description") 1.249 + }; 1.250 + ClassDoc[] enums = 1.251 + packageDoc.isIncluded() 1.252 + ? packageDoc.enums() 1.253 + : configuration.classDocCatalog.enums( 1.254 + Util.getPackageName(packageDoc)); 1.255 + if (enums.length > 0) { 1.256 + profilePackageWriter.addClassesSummary( 1.257 + enums, 1.258 + configuration.getText("doclet.Enum_Summary"), 1.259 + enumTableSummary, enumTableHeader, summaryContentTree); 1.260 + } 1.261 + } 1.262 + 1.263 + /** 1.264 + * Build the summary for the exceptions in this package. 1.265 + * 1.266 + * @param node the XML element that specifies which components to document 1.267 + * @param summaryContentTree the summary tree to which the exception summary will 1.268 + * be added 1.269 + */ 1.270 + public void buildExceptionSummary(XMLNode node, Content summaryContentTree) { 1.271 + String exceptionTableSummary = 1.272 + configuration.getText("doclet.Member_Table_Summary", 1.273 + configuration.getText("doclet.Exception_Summary"), 1.274 + configuration.getText("doclet.exceptions")); 1.275 + String[] exceptionTableHeader = new String[] { 1.276 + configuration.getText("doclet.Exception"), 1.277 + configuration.getText("doclet.Description") 1.278 + }; 1.279 + ClassDoc[] exceptions = 1.280 + packageDoc.isIncluded() 1.281 + ? packageDoc.exceptions() 1.282 + : configuration.classDocCatalog.exceptions( 1.283 + Util.getPackageName(packageDoc)); 1.284 + if (exceptions.length > 0) { 1.285 + profilePackageWriter.addClassesSummary( 1.286 + exceptions, 1.287 + configuration.getText("doclet.Exception_Summary"), 1.288 + exceptionTableSummary, exceptionTableHeader, summaryContentTree); 1.289 + } 1.290 + } 1.291 + 1.292 + /** 1.293 + * Build the summary for the errors in this package. 1.294 + * 1.295 + * @param node the XML element that specifies which components to document 1.296 + * @param summaryContentTree the summary tree to which the error summary will 1.297 + * be added 1.298 + */ 1.299 + public void buildErrorSummary(XMLNode node, Content summaryContentTree) { 1.300 + String errorTableSummary = 1.301 + configuration.getText("doclet.Member_Table_Summary", 1.302 + configuration.getText("doclet.Error_Summary"), 1.303 + configuration.getText("doclet.errors")); 1.304 + String[] errorTableHeader = new String[] { 1.305 + configuration.getText("doclet.Error"), 1.306 + configuration.getText("doclet.Description") 1.307 + }; 1.308 + ClassDoc[] errors = 1.309 + packageDoc.isIncluded() 1.310 + ? packageDoc.errors() 1.311 + : configuration.classDocCatalog.errors( 1.312 + Util.getPackageName(packageDoc)); 1.313 + if (errors.length > 0) { 1.314 + profilePackageWriter.addClassesSummary( 1.315 + errors, 1.316 + configuration.getText("doclet.Error_Summary"), 1.317 + errorTableSummary, errorTableHeader, summaryContentTree); 1.318 + } 1.319 + } 1.320 + 1.321 + /** 1.322 + * Build the summary for the annotation type in this package. 1.323 + * 1.324 + * @param node the XML element that specifies which components to document 1.325 + * @param summaryContentTree the summary tree to which the annotation type 1.326 + * summary will be added 1.327 + */ 1.328 + public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) { 1.329 + String annotationtypeTableSummary = 1.330 + configuration.getText("doclet.Member_Table_Summary", 1.331 + configuration.getText("doclet.Annotation_Types_Summary"), 1.332 + configuration.getText("doclet.annotationtypes")); 1.333 + String[] annotationtypeTableHeader = new String[] { 1.334 + configuration.getText("doclet.AnnotationType"), 1.335 + configuration.getText("doclet.Description") 1.336 + }; 1.337 + ClassDoc[] annotationTypes = 1.338 + packageDoc.isIncluded() 1.339 + ? packageDoc.annotationTypes() 1.340 + : configuration.classDocCatalog.annotationTypes( 1.341 + Util.getPackageName(packageDoc)); 1.342 + if (annotationTypes.length > 0) { 1.343 + profilePackageWriter.addClassesSummary( 1.344 + annotationTypes, 1.345 + configuration.getText("doclet.Annotation_Types_Summary"), 1.346 + annotationtypeTableSummary, annotationtypeTableHeader, 1.347 + summaryContentTree); 1.348 + } 1.349 + } 1.350 + 1.351 + /** 1.352 + * Build the description of the summary. 1.353 + * 1.354 + * @param node the XML element that specifies which components to document 1.355 + * @param packageContentTree the tree to which the package description will 1.356 + * be added 1.357 + */ 1.358 + public void buildPackageDescription(XMLNode node, Content packageContentTree) { 1.359 + if (configuration.nocomment) { 1.360 + return; 1.361 + } 1.362 + profilePackageWriter.addPackageDescription(packageContentTree); 1.363 + } 1.364 + 1.365 + /** 1.366 + * Build the tags of the summary. 1.367 + * 1.368 + * @param node the XML element that specifies which components to document 1.369 + * @param packageContentTree the tree to which the package tags will be added 1.370 + */ 1.371 + public void buildPackageTags(XMLNode node, Content packageContentTree) { 1.372 + if (configuration.nocomment) { 1.373 + return; 1.374 + } 1.375 + profilePackageWriter.addPackageTags(packageContentTree); 1.376 + } 1.377 +}