Sat, 07 Nov 2020 10:30:02 +0800
Added tag mips-jdk8u275-b01 for changeset eb6ee6a5f2fe
1 /*
2 * Copyright (c) 2013, 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 */
26 package com.sun.tools.doclets.internal.toolkit.builders;
28 import java.io.*;
30 import com.sun.javadoc.*;
31 import com.sun.tools.javac.jvm.Profile;
32 import com.sun.tools.doclets.internal.toolkit.*;
33 import com.sun.tools.doclets.internal.toolkit.util.*;
35 /**
36 * Builds the summary for a given profile package.
37 *
38 * <p><b>This is NOT part of any supported API.
39 * If you write code that depends on this, you do so at your own risk.
40 * This code and its internal interfaces are subject to change or
41 * deletion without notice.</b>
42 *
43 * @author Bhavesh Patel
44 */
45 public class ProfilePackageSummaryBuilder extends AbstractBuilder {
46 /**
47 * The root element of the profile package summary XML is {@value}.
48 */
49 public static final String ROOT = "PackageDoc";
51 /**
52 * The profile package being documented.
53 */
54 private final PackageDoc packageDoc;
56 /**
57 * The name of the profile being documented.
58 */
59 private final String profileName;
61 /**
62 * The value of the profile being documented.
63 */
64 private final int profileValue;
66 /**
67 * The doclet specific writer that will output the result.
68 */
69 private final ProfilePackageSummaryWriter profilePackageWriter;
71 /**
72 * The content that will be added to the profile package summary documentation tree.
73 */
74 private Content contentTree;
76 /**
77 * Construct a new ProfilePackageSummaryBuilder.
78 *
79 * @param context the build context.
80 * @param pkg the profile package being documented.
81 * @param profilePackageWriter the doclet specific writer that will output the
82 * result.
83 * @param profile the profile being documented.
84 */
85 private ProfilePackageSummaryBuilder(Context context,
86 PackageDoc pkg, ProfilePackageSummaryWriter profilePackageWriter,
87 Profile profile) {
88 super(context);
89 this.packageDoc = pkg;
90 this.profilePackageWriter = profilePackageWriter;
91 this.profileName = profile.name;
92 this.profileValue = profile.value;
93 }
95 /**
96 * Construct a new ProfilePackageSummaryBuilder.
97 *
98 * @param context the build context.
99 * @param pkg the profile package being documented.
100 * @param profilePackageWriter the doclet specific writer that will output the
101 * result.
102 * @param profile the profile being documented.
103 *
104 * @return an instance of a ProfilePackageSummaryBuilder.
105 */
106 public static ProfilePackageSummaryBuilder getInstance(Context context,
107 PackageDoc pkg, ProfilePackageSummaryWriter profilePackageWriter,
108 Profile profile) {
109 return new ProfilePackageSummaryBuilder(context, pkg, profilePackageWriter,
110 profile);
111 }
113 /**
114 * Build the profile package summary.
115 */
116 public void build() throws IOException {
117 if (profilePackageWriter == null) {
118 //Doclet does not support this output.
119 return;
120 }
121 build(layoutParser.parseXML(ROOT), contentTree);
122 }
124 /**
125 * {@inheritDoc}
126 */
127 public String getName() {
128 return ROOT;
129 }
131 /**
132 * Build the profile package documentation.
133 *
134 * @param node the XML element that specifies which components to document
135 * @param contentTree the content tree to which the documentation will be added
136 */
137 public void buildPackageDoc(XMLNode node, Content contentTree) throws Exception {
138 contentTree = profilePackageWriter.getPackageHeader(
139 Util.getPackageName(packageDoc));
140 buildChildren(node, contentTree);
141 profilePackageWriter.addPackageFooter(contentTree);
142 profilePackageWriter.printDocument(contentTree);
143 profilePackageWriter.close();
144 Util.copyDocFiles(configuration, packageDoc);
145 }
147 /**
148 * Build the content for the profile package doc.
149 *
150 * @param node the XML element that specifies which components to document
151 * @param contentTree the content tree to which the package contents
152 * will be added
153 */
154 public void buildContent(XMLNode node, Content contentTree) {
155 Content packageContentTree = profilePackageWriter.getContentHeader();
156 buildChildren(node, packageContentTree);
157 contentTree.addContent(packageContentTree);
158 }
160 /**
161 * Build the profile package summary.
162 *
163 * @param node the XML element that specifies which components to document
164 * @param packageContentTree the package content tree to which the summaries will
165 * be added
166 */
167 public void buildSummary(XMLNode node, Content packageContentTree) {
168 Content summaryContentTree = profilePackageWriter.getSummaryHeader();
169 buildChildren(node, summaryContentTree);
170 packageContentTree.addContent(summaryContentTree);
171 }
173 /**
174 * Build the summary for the interfaces in this package.
175 *
176 * @param node the XML element that specifies which components to document
177 * @param summaryContentTree the summary tree to which the interface summary
178 * will be added
179 */
180 public void buildInterfaceSummary(XMLNode node, Content summaryContentTree) {
181 String interfaceTableSummary =
182 configuration.getText("doclet.Member_Table_Summary",
183 configuration.getText("doclet.Interface_Summary"),
184 configuration.getText("doclet.interfaces"));
185 String[] interfaceTableHeader = new String[] {
186 configuration.getText("doclet.Interface"),
187 configuration.getText("doclet.Description")
188 };
189 ClassDoc[] interfaces =
190 packageDoc.isIncluded()
191 ? packageDoc.interfaces()
192 : configuration.classDocCatalog.interfaces(
193 Util.getPackageName(packageDoc));
194 if (interfaces.length > 0) {
195 profilePackageWriter.addClassesSummary(
196 interfaces,
197 configuration.getText("doclet.Interface_Summary"),
198 interfaceTableSummary, interfaceTableHeader, summaryContentTree);
199 }
200 }
202 /**
203 * Build the summary for the classes in this package.
204 *
205 * @param node the XML element that specifies which components to document
206 * @param summaryContentTree the summary tree to which the class summary will
207 * be added
208 */
209 public void buildClassSummary(XMLNode node, Content summaryContentTree) {
210 String classTableSummary =
211 configuration.getText("doclet.Member_Table_Summary",
212 configuration.getText("doclet.Class_Summary"),
213 configuration.getText("doclet.classes"));
214 String[] classTableHeader = new String[] {
215 configuration.getText("doclet.Class"),
216 configuration.getText("doclet.Description")
217 };
218 ClassDoc[] classes =
219 packageDoc.isIncluded()
220 ? packageDoc.ordinaryClasses()
221 : configuration.classDocCatalog.ordinaryClasses(
222 Util.getPackageName(packageDoc));
223 if (classes.length > 0) {
224 profilePackageWriter.addClassesSummary(
225 classes,
226 configuration.getText("doclet.Class_Summary"),
227 classTableSummary, classTableHeader, summaryContentTree);
228 }
229 }
231 /**
232 * Build the summary for the enums in this package.
233 *
234 * @param node the XML element that specifies which components to document
235 * @param summaryContentTree the summary tree to which the enum summary will
236 * be added
237 */
238 public void buildEnumSummary(XMLNode node, Content summaryContentTree) {
239 String enumTableSummary =
240 configuration.getText("doclet.Member_Table_Summary",
241 configuration.getText("doclet.Enum_Summary"),
242 configuration.getText("doclet.enums"));
243 String[] enumTableHeader = new String[] {
244 configuration.getText("doclet.Enum"),
245 configuration.getText("doclet.Description")
246 };
247 ClassDoc[] enums =
248 packageDoc.isIncluded()
249 ? packageDoc.enums()
250 : configuration.classDocCatalog.enums(
251 Util.getPackageName(packageDoc));
252 if (enums.length > 0) {
253 profilePackageWriter.addClassesSummary(
254 enums,
255 configuration.getText("doclet.Enum_Summary"),
256 enumTableSummary, enumTableHeader, summaryContentTree);
257 }
258 }
260 /**
261 * Build the summary for the exceptions in this package.
262 *
263 * @param node the XML element that specifies which components to document
264 * @param summaryContentTree the summary tree to which the exception summary will
265 * be added
266 */
267 public void buildExceptionSummary(XMLNode node, Content summaryContentTree) {
268 String exceptionTableSummary =
269 configuration.getText("doclet.Member_Table_Summary",
270 configuration.getText("doclet.Exception_Summary"),
271 configuration.getText("doclet.exceptions"));
272 String[] exceptionTableHeader = new String[] {
273 configuration.getText("doclet.Exception"),
274 configuration.getText("doclet.Description")
275 };
276 ClassDoc[] exceptions =
277 packageDoc.isIncluded()
278 ? packageDoc.exceptions()
279 : configuration.classDocCatalog.exceptions(
280 Util.getPackageName(packageDoc));
281 if (exceptions.length > 0) {
282 profilePackageWriter.addClassesSummary(
283 exceptions,
284 configuration.getText("doclet.Exception_Summary"),
285 exceptionTableSummary, exceptionTableHeader, summaryContentTree);
286 }
287 }
289 /**
290 * Build the summary for the errors in this package.
291 *
292 * @param node the XML element that specifies which components to document
293 * @param summaryContentTree the summary tree to which the error summary will
294 * be added
295 */
296 public void buildErrorSummary(XMLNode node, Content summaryContentTree) {
297 String errorTableSummary =
298 configuration.getText("doclet.Member_Table_Summary",
299 configuration.getText("doclet.Error_Summary"),
300 configuration.getText("doclet.errors"));
301 String[] errorTableHeader = new String[] {
302 configuration.getText("doclet.Error"),
303 configuration.getText("doclet.Description")
304 };
305 ClassDoc[] errors =
306 packageDoc.isIncluded()
307 ? packageDoc.errors()
308 : configuration.classDocCatalog.errors(
309 Util.getPackageName(packageDoc));
310 if (errors.length > 0) {
311 profilePackageWriter.addClassesSummary(
312 errors,
313 configuration.getText("doclet.Error_Summary"),
314 errorTableSummary, errorTableHeader, summaryContentTree);
315 }
316 }
318 /**
319 * Build the summary for the annotation type in this package.
320 *
321 * @param node the XML element that specifies which components to document
322 * @param summaryContentTree the summary tree to which the annotation type
323 * summary will be added
324 */
325 public void buildAnnotationTypeSummary(XMLNode node, Content summaryContentTree) {
326 String annotationtypeTableSummary =
327 configuration.getText("doclet.Member_Table_Summary",
328 configuration.getText("doclet.Annotation_Types_Summary"),
329 configuration.getText("doclet.annotationtypes"));
330 String[] annotationtypeTableHeader = new String[] {
331 configuration.getText("doclet.AnnotationType"),
332 configuration.getText("doclet.Description")
333 };
334 ClassDoc[] annotationTypes =
335 packageDoc.isIncluded()
336 ? packageDoc.annotationTypes()
337 : configuration.classDocCatalog.annotationTypes(
338 Util.getPackageName(packageDoc));
339 if (annotationTypes.length > 0) {
340 profilePackageWriter.addClassesSummary(
341 annotationTypes,
342 configuration.getText("doclet.Annotation_Types_Summary"),
343 annotationtypeTableSummary, annotationtypeTableHeader,
344 summaryContentTree);
345 }
346 }
348 /**
349 * Build the description of the summary.
350 *
351 * @param node the XML element that specifies which components to document
352 * @param packageContentTree the tree to which the package description will
353 * be added
354 */
355 public void buildPackageDescription(XMLNode node, Content packageContentTree) {
356 if (configuration.nocomment) {
357 return;
358 }
359 profilePackageWriter.addPackageDescription(packageContentTree);
360 }
362 /**
363 * Build the tags of the summary.
364 *
365 * @param node the XML element that specifies which components to document
366 * @param packageContentTree the tree to which the package tags will be added
367 */
368 public void buildPackageTags(XMLNode node, Content packageContentTree) {
369 if (configuration.nocomment) {
370 return;
371 }
372 profilePackageWriter.addPackageTags(packageContentTree);
373 }
374 }