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 */
25
26 package com.sun.tools.doclets.internal.toolkit.builders;
27
28 import java.io.*;
29
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.*;
34
35 /**
36 * Builds the summary for a given profile.
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 ProfileSummaryBuilder extends AbstractBuilder {
46 /**
47 * The root element of the profile summary XML is {@value}.
48 */
49 public static final String ROOT = "ProfileDoc";
50
51 /**
52 * The profile being documented.
53 */
54 private final Profile profile;
55
56 /**
57 * The doclet specific writer that will output the result.
58 */
59 private final ProfileSummaryWriter profileWriter;
60
61 /**
62 * The content that will be added to the profile summary documentation tree.
63 */
64 private Content contentTree;
65
66 /**
67 * The profile package being documented.
68 */
69 private PackageDoc pkg;
70
71 /**
72 * Construct a new ProfileSummaryBuilder.
73 *
74 * @param context the build context.
75 * @param profile the profile being documented.
76 * @param profileWriter the doclet specific writer that will output the
77 * result.
78 */
79 private ProfileSummaryBuilder(Context context,
80 Profile profile, ProfileSummaryWriter profileWriter) {
81 super(context);
82 this.profile = profile;
83 this.profileWriter = profileWriter;
84 }
85
86 /**
87 * Construct a new ProfileSummaryBuilder.
88 *
89 * @param context the build context.
90 * @param profile the profile being documented.
91 * @param profileWriter the doclet specific writer that will output the
92 * result.
93 *
94 * @return an instance of a ProfileSummaryBuilder.
95 */
96 public static ProfileSummaryBuilder getInstance(Context context,
97 Profile profile, ProfileSummaryWriter profileWriter) {
98 return new ProfileSummaryBuilder(context, profile, profileWriter);
99 }
100
101 /**
102 * Build the profile summary.
103 */
104 public void build() throws IOException {
105 if (profileWriter == null) {
106 //Doclet does not support this output.
107 return;
108 }
109 build(layoutParser.parseXML(ROOT), contentTree);
110 }
111
112 /**
113 * {@inheritDoc}
114 */
115 public String getName() {
116 return ROOT;
117 }
118
119 /**
120 * Build the profile documentation.
121 *
122 * @param node the XML element that specifies which components to document
123 * @param contentTree the content tree to which the documentation will be added
124 */
125 public void buildProfileDoc(XMLNode node, Content contentTree) throws Exception {
126 contentTree = profileWriter.getProfileHeader(profile.name);
127 buildChildren(node, contentTree);
128 profileWriter.addProfileFooter(contentTree);
129 profileWriter.printDocument(contentTree);
130 profileWriter.close();
131 Util.copyDocFiles(configuration, DocPaths.profileSummary(profile.name));
132 }
133
134 /**
135 * Build the content for the profile doc.
136 *
137 * @param node the XML element that specifies which components to document
138 * @param contentTree the content tree to which the profile contents
139 * will be added
140 */
141 public void buildContent(XMLNode node, Content contentTree) {
142 Content profileContentTree = profileWriter.getContentHeader();
143 buildChildren(node, profileContentTree);
144 contentTree.addContent(profileContentTree);
145 }
146
147 /**
148 * Build the profile summary.
149 *
150 * @param node the XML element that specifies which components to document
151 * @param profileContentTree the profile content tree to which the summaries will
152 * be added
153 */
154 public void buildSummary(XMLNode node, Content profileContentTree) {
155 Content summaryContentTree = profileWriter.getSummaryHeader();
156 buildChildren(node, summaryContentTree);
157 profileContentTree.addContent(profileWriter.getSummaryTree(summaryContentTree));
158 }
159
160 /**
161 * Build the profile package summary.
162 *
163 * @param node the XML element that specifies which components to document
164 * @param summaryContentTree the content tree to which the summaries will
165 * be added
166 */
167 public void buildPackageSummary(XMLNode node, Content summaryContentTree) {
168 PackageDoc[] packages = configuration.profilePackages.get(profile.name);
169 for (int i = 0; i < packages.length; i++) {
170 this.pkg = packages[i];
171 Content packageSummaryContentTree = profileWriter.getPackageSummaryHeader(this.pkg);
172 buildChildren(node, packageSummaryContentTree);
173 summaryContentTree.addContent(profileWriter.getPackageSummaryTree(
174 packageSummaryContentTree));
175 }
176 }
177
178 /**
179 * Build the summary for the interfaces in the package.
180 *
181 * @param node the XML element that specifies which components to document
182 * @param packageSummaryContentTree the tree to which the interface summary
183 * will be added
184 */
185 public void buildInterfaceSummary(XMLNode node, Content packageSummaryContentTree) {
186 String interfaceTableSummary =
187 configuration.getText("doclet.Member_Table_Summary",
188 configuration.getText("doclet.Interface_Summary"),
189 configuration.getText("doclet.interfaces"));
190 String[] interfaceTableHeader = new String[] {
191 configuration.getText("doclet.Interface"),
192 configuration.getText("doclet.Description")
193 };
194 ClassDoc[] interfaces = pkg.interfaces();
195 if (interfaces.length > 0) {
196 profileWriter.addClassesSummary(
197 interfaces,
198 configuration.getText("doclet.Interface_Summary"),
199 interfaceTableSummary, interfaceTableHeader, packageSummaryContentTree);
200 }
201 }
202
203 /**
204 * Build the summary for the classes in the package.
205 *
206 * @param node the XML element that specifies which components to document
207 * @param packageSummaryContentTree the tree to which the class summary will
208 * be added
209 */
210 public void buildClassSummary(XMLNode node, Content packageSummaryContentTree) {
211 String classTableSummary =
212 configuration.getText("doclet.Member_Table_Summary",
213 configuration.getText("doclet.Class_Summary"),
214 configuration.getText("doclet.classes"));
215 String[] classTableHeader = new String[] {
216 configuration.getText("doclet.Class"),
217 configuration.getText("doclet.Description")
218 };
219 ClassDoc[] classes = pkg.ordinaryClasses();
220 if (classes.length > 0) {
221 profileWriter.addClassesSummary(
222 classes,
223 configuration.getText("doclet.Class_Summary"),
224 classTableSummary, classTableHeader, packageSummaryContentTree);
225 }
226 }
227
228 /**
229 * Build the summary for the enums in the package.
230 *
231 * @param node the XML element that specifies which components to document
232 * @param packageSummaryContentTree the tree to which the enum summary will
233 * be added
234 */
235 public void buildEnumSummary(XMLNode node, Content packageSummaryContentTree) {
236 String enumTableSummary =
237 configuration.getText("doclet.Member_Table_Summary",
238 configuration.getText("doclet.Enum_Summary"),
239 configuration.getText("doclet.enums"));
240 String[] enumTableHeader = new String[] {
241 configuration.getText("doclet.Enum"),
242 configuration.getText("doclet.Description")
243 };
244 ClassDoc[] enums = pkg.enums();
245 if (enums.length > 0) {
246 profileWriter.addClassesSummary(
247 enums,
248 configuration.getText("doclet.Enum_Summary"),
249 enumTableSummary, enumTableHeader, packageSummaryContentTree);
250 }
251 }
252
253 /**
254 * Build the summary for the exceptions in the package.
255 *
256 * @param node the XML element that specifies which components to document
257 * @param packageSummaryContentTree the tree to which the exception summary will
258 * be added
259 */
260 public void buildExceptionSummary(XMLNode node, Content packageSummaryContentTree) {
261 String exceptionTableSummary =
262 configuration.getText("doclet.Member_Table_Summary",
263 configuration.getText("doclet.Exception_Summary"),
264 configuration.getText("doclet.exceptions"));
265 String[] exceptionTableHeader = new String[] {
266 configuration.getText("doclet.Exception"),
267 configuration.getText("doclet.Description")
268 };
269 ClassDoc[] exceptions = pkg.exceptions();
270 if (exceptions.length > 0) {
271 profileWriter.addClassesSummary(
272 exceptions,
273 configuration.getText("doclet.Exception_Summary"),
274 exceptionTableSummary, exceptionTableHeader, packageSummaryContentTree);
275 }
276 }
277
278 /**
279 * Build the summary for the errors in the package.
280 *
281 * @param node the XML element that specifies which components to document
282 * @param packageSummaryContentTree the tree to which the error summary will
283 * be added
284 */
285 public void buildErrorSummary(XMLNode node, Content packageSummaryContentTree) {
286 String errorTableSummary =
287 configuration.getText("doclet.Member_Table_Summary",
288 configuration.getText("doclet.Error_Summary"),
289 configuration.getText("doclet.errors"));
290 String[] errorTableHeader = new String[] {
291 configuration.getText("doclet.Error"),
292 configuration.getText("doclet.Description")
293 };
294 ClassDoc[] errors = pkg.errors();
295 if (errors.length > 0) {
296 profileWriter.addClassesSummary(
297 errors,
298 configuration.getText("doclet.Error_Summary"),
299 errorTableSummary, errorTableHeader, packageSummaryContentTree);
300 }
301 }
302
303 /**
304 * Build the summary for the annotation type in the package.
305 *
306 * @param node the XML element that specifies which components to document
307 * @param packageSummaryContentTree the tree to which the annotation type
308 * summary will be added
309 */
310 public void buildAnnotationTypeSummary(XMLNode node, Content packageSummaryContentTree) {
311 String annotationtypeTableSummary =
312 configuration.getText("doclet.Member_Table_Summary",
313 configuration.getText("doclet.Annotation_Types_Summary"),
314 configuration.getText("doclet.annotationtypes"));
315 String[] annotationtypeTableHeader = new String[] {
316 configuration.getText("doclet.AnnotationType"),
317 configuration.getText("doclet.Description")
318 };
319 ClassDoc[] annotationTypes = pkg.annotationTypes();
320 if (annotationTypes.length > 0) {
321 profileWriter.addClassesSummary(
322 annotationTypes,
323 configuration.getText("doclet.Annotation_Types_Summary"),
324 annotationtypeTableSummary, annotationtypeTableHeader,
325 packageSummaryContentTree);
326 }
327 }
328 }