Thu, 02 Oct 2008 19:58:40 -0700
6754988: Update copyright year
Summary: Update for files that have been modified starting July 2008
Reviewed-by: ohair, tbell
1 /*
2 * Copyright 2003 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
26 package com.sun.tools.doclets.internal.toolkit.builders;
28 import com.sun.tools.doclets.internal.toolkit.util.*;
29 import com.sun.tools.doclets.internal.toolkit.*;
30 import com.sun.javadoc.*;
31 import java.io.*;
32 import java.util.*;
33 import java.lang.reflect.*;
35 /**
36 * Builds the summary for a given package.
37 *
38 * This code is not part of an API.
39 * It is implementation that is subject to change.
40 * Do not use it as an API
41 *
42 * @author Jamie Ho
43 * @since 1.5
44 */
45 public class PackageSummaryBuilder extends AbstractBuilder {
47 /**
48 * The root element of the package summary XML is {@value}.
49 */
50 public static final String ROOT = "PackageDoc";
52 /**
53 * The package being documented.
54 */
55 private PackageDoc packageDoc;
57 /**
58 * The doclet specific writer that will output the result.
59 */
60 private PackageSummaryWriter packageWriter;
62 private PackageSummaryBuilder(Configuration configuration) {
63 super(configuration);
64 }
66 /**
67 * Construct a new PackageSummaryBuilder.
68 * @param configuration the current configuration of the doclet.
69 * @param pkg the package being documented.
70 * @param packageWriter the doclet specific writer that will output the
71 * result.
72 *
73 * @return an instance of a PackageSummaryBuilder.
74 */
75 public static PackageSummaryBuilder getInstance(
76 Configuration configuration,
77 PackageDoc pkg,
78 PackageSummaryWriter packageWriter) {
79 PackageSummaryBuilder builder =
80 new PackageSummaryBuilder(configuration);
81 builder.packageDoc = pkg;
82 builder.packageWriter = packageWriter;
83 return builder;
84 }
86 /**
87 * {@inheritDoc}
88 */
89 public void invokeMethod(
90 String methodName,
91 Class[] paramClasses,
92 Object[] params)
93 throws Exception {
94 if (DEBUG) {
95 configuration.root.printError(
96 "DEBUG: " + this.getClass().getName() + "." + methodName);
97 }
98 Method method = this.getClass().getMethod(methodName, paramClasses);
99 method.invoke(this, params);
100 }
102 /**
103 * Build the package summary.
104 */
105 public void build() throws IOException {
106 if (packageWriter == null) {
107 //Doclet does not support this output.
108 return;
109 }
110 build(LayoutParser.getInstance(configuration).parseXML(ROOT));
111 }
113 /**
114 * {@inheritDoc}
115 */
116 public String getName() {
117 return ROOT;
118 }
120 /**
121 * Build the package documentation.
122 */
123 public void buildPackageDoc(List elements) throws Exception {
124 build(elements);
125 packageWriter.close();
126 Util.copyDocFiles(
127 configuration,
128 Util.getPackageSourcePath(configuration, packageDoc),
129 DirectoryManager.getDirectoryPath(packageDoc)
130 + File.separator
131 + DocletConstants.DOC_FILES_DIR_NAME,
132 true);
133 }
135 /**
136 * Build the header of the summary.
137 */
138 public void buildPackageHeader() {
139 packageWriter.writePackageHeader(Util.getPackageName(packageDoc));
140 }
142 /**
143 * Build the description of the summary.
144 */
145 public void buildPackageDescription() {
146 if (configuration.nocomment) {
147 return;
148 }
149 packageWriter.writePackageDescription();
150 }
152 /**
153 * Build the tags of the summary.
154 */
155 public void buildPackageTags() {
156 if (configuration.nocomment) {
157 return;
158 }
159 packageWriter.writePackageTags();
160 }
162 /**
163 * Build the package summary.
164 */
165 public void buildSummary(List elements) {
166 build(elements);
167 }
169 /**
170 * Build the overall header.
171 */
172 public void buildSummaryHeader() {
173 packageWriter.writeSummaryHeader();
174 }
176 /**
177 * Build the overall footer.
178 */
179 public void buildSummaryFooter() {
180 packageWriter.writeSummaryFooter();
181 }
183 /**
184 * Build the summary for the classes in this package.
185 */
186 public void buildClassSummary() {
187 ClassDoc[] classes =
188 packageDoc.isIncluded()
189 ? packageDoc.ordinaryClasses()
190 : configuration.classDocCatalog.ordinaryClasses(
191 Util.getPackageName(packageDoc));
192 if (classes.length > 0) {
193 packageWriter.writeClassesSummary(
194 classes,
195 configuration.getText("doclet.Class_Summary"));
196 }
197 }
199 /**
200 * Build the summary for the interfaces in this package.
201 */
202 public void buildInterfaceSummary() {
203 ClassDoc[] interfaces =
204 packageDoc.isIncluded()
205 ? packageDoc.interfaces()
206 : configuration.classDocCatalog.interfaces(
207 Util.getPackageName(packageDoc));
208 if (interfaces.length > 0) {
209 packageWriter.writeClassesSummary(
210 interfaces,
211 configuration.getText("doclet.Interface_Summary"));
212 }
213 }
215 /**
216 * Build the summary for the enums in this package.
217 */
218 public void buildAnnotationTypeSummary() {
219 ClassDoc[] annotationTypes =
220 packageDoc.isIncluded()
221 ? packageDoc.annotationTypes()
222 : configuration.classDocCatalog.annotationTypes(
223 Util.getPackageName(packageDoc));
224 if (annotationTypes.length > 0) {
225 packageWriter.writeClassesSummary(
226 annotationTypes,
227 configuration.getText("doclet.Annotation_Types_Summary"));
228 }
229 }
231 /**
232 * Build the summary for the enums in this package.
233 */
234 public void buildEnumSummary() {
235 ClassDoc[] enums =
236 packageDoc.isIncluded()
237 ? packageDoc.enums()
238 : configuration.classDocCatalog.enums(
239 Util.getPackageName(packageDoc));
240 if (enums.length > 0) {
241 packageWriter.writeClassesSummary(
242 enums,
243 configuration.getText("doclet.Enum_Summary"));
244 }
245 }
247 /**
248 * Build the summary for the exceptions in this package.
249 */
250 public void buildExceptionSummary() {
251 ClassDoc[] exceptions =
252 packageDoc.isIncluded()
253 ? packageDoc.exceptions()
254 : configuration.classDocCatalog.exceptions(
255 Util.getPackageName(packageDoc));
256 if (exceptions.length > 0) {
257 packageWriter.writeClassesSummary(
258 exceptions,
259 configuration.getText("doclet.Exception_Summary"));
260 }
261 }
263 /**
264 * Build the summary for the errors in this package.
265 */
266 public void buildErrorSummary() {
267 ClassDoc[] errors =
268 packageDoc.isIncluded()
269 ? packageDoc.errors()
270 : configuration.classDocCatalog.errors(
271 Util.getPackageName(packageDoc));
272 if (errors.length > 0) {
273 packageWriter.writeClassesSummary(
274 errors,
275 configuration.getText("doclet.Error_Summary"));
276 }
277 }
279 /**
280 * Build the footer of the summary.
281 */
282 public void buildPackageFooter() {
283 packageWriter.writePackageFooter();
284 }
285 }