001 /*
002 * Copyright 2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package com.sun.tools.doclets.internal.toolkit.builders;
027
028 import com.sun.tools.doclets.internal.toolkit.util.*;
029 import com.sun.tools.doclets.internal.toolkit.*;
030 import com.sun.javadoc.*;
031 import java.io.*;
032 import java.util.*;
033 import java.lang.reflect.*;
034
035 /**
036 * Builds the summary for a given package.
037 *
038 * This code is not part of an API.
039 * It is implementation that is subject to change.
040 * Do not use it as an API
041 *
042 * @author Jamie Ho
043 * @since 1.5
044 */
045 public class PackageSummaryBuilder extends AbstractBuilder {
046
047 /**
048 * The root element of the package summary XML is {@value}.
049 */
050 public static final String ROOT = "PackageDoc";
051
052 /**
053 * The package being documented.
054 */
055 private PackageDoc packageDoc;
056
057 /**
058 * The doclet specific writer that will output the result.
059 */
060 private PackageSummaryWriter packageWriter;
061
062 private PackageSummaryBuilder(Configuration configuration) {
063 super(configuration);
064 }
065
066 /**
067 * Construct a new PackageSummaryBuilder.
068 * @param configuration the current configuration of the doclet.
069 * @param pkg the package being documented.
070 * @param packageWriter the doclet specific writer that will output the
071 * result.
072 *
073 * @return an instance of a PackageSummaryBuilder.
074 */
075 public static PackageSummaryBuilder getInstance(
076 Configuration configuration,
077 PackageDoc pkg,
078 PackageSummaryWriter packageWriter) {
079 PackageSummaryBuilder builder =
080 new PackageSummaryBuilder(configuration);
081 builder.packageDoc = pkg;
082 builder.packageWriter = packageWriter;
083 return builder;
084 }
085
086 /**
087 * {@inheritDoc}
088 */
089 public void invokeMethod(
090 String methodName,
091 Class<?>[] paramClasses,
092 Object[] params)
093 throws Exception {
094 if (DEBUG) {
095 configuration.root.printError(
096 "DEBUG: " + this.getClass().getName() + "." + methodName);
097 }
098 Method method = this.getClass().getMethod(methodName, paramClasses);
099 method.invoke(this, params);
100 }
101
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 }
112
113 /**
114 * {@inheritDoc}
115 */
116 public String getName() {
117 return ROOT;
118 }
119
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 }
134
135 /**
136 * Build the header of the summary.
137 */
138 public void buildPackageHeader() {
139 packageWriter.writePackageHeader(Util.getPackageName(packageDoc));
140 }
141
142 /**
143 * Build the description of the summary.
144 */
145 public void buildPackageDescription() {
146 if (configuration.nocomment) {
147 return;
148 }
149 packageWriter.writePackageDescription();
150 }
151
152 /**
153 * Build the tags of the summary.
154 */
155 public void buildPackageTags() {
156 if (configuration.nocomment) {
157 return;
158 }
159 packageWriter.writePackageTags();
160 }
161
162 /**
163 * Build the package summary.
164 */
165 public void buildSummary(List<?> elements) {
166 build(elements);
167 }
168
169 /**
170 * Build the overall header.
171 */
172 public void buildSummaryHeader() {
173 packageWriter.writeSummaryHeader();
174 }
175
176 /**
177 * Build the overall footer.
178 */
179 public void buildSummaryFooter() {
180 packageWriter.writeSummaryFooter();
181 }
182
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 }
198
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 }
214
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 }
230
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 }
246
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 }
262
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 }
278
279 /**
280 * Build the footer of the summary.
281 */
282 public void buildPackageFooter() {
283 packageWriter.writePackageFooter();
284 }
285 }