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-2008 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 class.
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 ClassBuilder extends AbstractBuilder {
47 /**
48 * The root element of the class XML is {@value}.
49 */
50 public static final String ROOT = "ClassDoc";
52 /**
53 * The class being documented.
54 */
55 private ClassDoc classDoc;
57 /**
58 * The doclet specific writer.
59 */
60 private ClassWriter writer;
62 /**
63 * Keep track of whether or not this classdoc is an interface.
64 */
65 private boolean isInterface = false;
67 /**
68 * Keep track of whether or not this classdoc is an enum.
69 */
70 private boolean isEnum = false;
72 /**
73 * Construct a new ClassBuilder.
74 *
75 * @param configuration the current configuration of the
76 * doclet.
77 */
78 private ClassBuilder(Configuration configuration) {
79 super(configuration);
80 }
82 /**
83 * Construct a new ClassBuilder.
84 *
85 * @param configuration the current configuration of the doclet.
86 * @param classDoc the class being documented.
87 * @param writer the doclet specific writer.
88 */
89 public static ClassBuilder getInstance(Configuration configuration,
90 ClassDoc classDoc, ClassWriter writer)
91 throws Exception {
92 ClassBuilder builder = new ClassBuilder(configuration);
93 builder.configuration = configuration;
94 builder.classDoc = classDoc;
95 builder.writer = writer;
96 if (classDoc.isInterface()) {
97 builder.isInterface = true;
98 } else if (classDoc.isEnum()) {
99 builder.isEnum = true;
100 Util.setEnumDocumentation(configuration, classDoc);
101 }
102 if(containingPackagesSeen == null) {
103 containingPackagesSeen = new HashSet<String>();
104 }
105 return builder;
106 }
108 /**
109 * {@inheritDoc}
110 */
111 public void invokeMethod(String methodName, Class[] paramClasses,
112 Object[] params)
113 throws Exception {
114 if (DEBUG) {
115 configuration.root.printError("DEBUG: " + this.getClass().getName()
116 + "." + methodName);
117 }
118 Method method = this.getClass().getMethod(methodName, paramClasses);
119 method.invoke(this, params);
120 }
122 /**
123 * {@inheritDoc}
124 */
125 public void build() throws IOException {
126 build(LayoutParser.getInstance(configuration).parseXML(ROOT));
127 }
129 /**
130 * {@inheritDoc}
131 */
132 public String getName() {
133 return ROOT;
134 }
136 /**
137 * Handles the <ClassDoc> tag.
138 *
139 * @param elements the XML elements that specify how to document a class.
140 */
141 public void buildClassDoc(List elements) throws Exception {
142 build(elements);
143 writer.close();
144 copyDocFiles();
145 }
148 /**
149 * Copy the doc files for the current ClassDoc if necessary.
150 */
151 private void copyDocFiles() {
152 PackageDoc containingPackage = classDoc.containingPackage();
153 if((configuration.packages == null ||
154 Arrays.binarySearch(configuration.packages,
155 containingPackage) < 0) &&
156 ! containingPackagesSeen.contains(containingPackage.name())){
157 //Only copy doc files dir if the containing package is not
158 //documented AND if we have not documented a class from the same
159 //package already. Otherwise, we are making duplicate copies.
160 Util.copyDocFiles(configuration,
161 Util.getPackageSourcePath(configuration,
162 classDoc.containingPackage()) +
163 DirectoryManager.getDirectoryPath(classDoc.containingPackage())
164 + File.separator, DocletConstants.DOC_FILES_DIR_NAME, true);
165 containingPackagesSeen.add(containingPackage.name());
166 }
167 }
169 /**
170 * Build the header of the page.
171 */
172 public void buildClassHeader() {
173 String key;
174 if (isInterface) {
175 key = "doclet.Interface";
176 } else if (isEnum) {
177 key = "doclet.Enum";
178 } else {
179 key = "doclet.Class";
180 }
182 writer.writeHeader(configuration.getText(key) + " " + classDoc.name());
183 }
185 /**
186 * Build the class tree documentation.
187 */
188 public void buildClassTree() {
189 writer.writeClassTree();
190 }
192 /**
193 * If this is a class, list all interfaces
194 * implemented by this class.
195 */
196 public void buildImplementedInterfacesInfo() {
197 writer.writeImplementedInterfacesInfo();
198 }
200 /**
201 * If this is an interface, list all super interfaces.
202 */
203 public void buildSuperInterfacesInfo() {
204 writer.writeSuperInterfacesInfo();
205 }
207 /**
208 * List the parameters of this class.
209 */
210 public void buildTypeParamInfo() {
211 writer.writeTypeParamInfo();
212 }
214 /**
215 * List all the classes extend this one.
216 */
217 public void buildSubClassInfo() {
218 writer.writeSubClassInfo();
219 }
221 /**
222 * List all the interfaces that extend this one.
223 */
224 public void buildSubInterfacesInfo() {
225 writer.writeSubInterfacesInfo();
226 }
228 /**
229 * If this is an interface, list all classes that implement this interface.
230 */
231 public void buildInterfaceUsageInfo () {
232 writer.writeInterfaceUsageInfo();
233 }
235 /**
236 * If this is an inner class or interface, list the enclosing class or
237 * interface.
238 */
239 public void buildNestedClassInfo () {
240 writer.writeNestedClassInfo();
241 }
243 /**
244 * If this class is deprecated, print the appropriate information.
245 */
246 public void buildDeprecationInfo () {
247 writer.writeClassDeprecationInfo();
248 }
250 /**
251 * Build the signature of the current class.
252 */
253 public void buildClassSignature() {
254 StringBuffer modifiers = new StringBuffer(classDoc.modifiers() + " ");
255 if (isEnum) {
256 modifiers.append("enum ");
257 int index;
258 if ((index = modifiers.indexOf("abstract")) >= 0) {
259 modifiers.delete(index, index + (new String("abstract")).length());
260 modifiers = new StringBuffer(
261 Util.replaceText(modifiers.toString(), " ", " "));
262 }
263 if ((index = modifiers.indexOf("final")) >= 0) {
264 modifiers.delete(index, index + (new String("final")).length());
265 modifiers = new StringBuffer(
266 Util.replaceText(modifiers.toString(), " ", " "));
267 }
268 //} else if (classDoc.isAnnotationType()) {
269 //modifiers.append("@interface ");
270 } else if (! isInterface) {
271 modifiers.append("class ");
272 }
273 writer.writeClassSignature(modifiers.toString());
274 }
276 /**
277 * Build the class description.
278 */
279 public void buildClassDescription() {
280 writer.writeClassDescription();
281 }
283 /**
284 * Build the tag information for the current class.
285 */
286 public void buildClassTagInfo() {
287 writer.writeClassTagInfo();
288 }
290 /**
291 * Build the contents of the page.
292 *
293 * @param elements the XML elements that specify how a member summary is
294 * documented.
295 */
296 public void buildMemberSummary(List elements) throws Exception {
297 configuration.getBuilderFactory().
298 getMemberSummaryBuilder(writer).build(elements);
299 writer.completeMemberSummaryBuild();
300 }
302 /**
303 * Build the enum constants documentation.
304 *
305 * @param elements the XML elements that specify how a enum constants are
306 * documented.
307 */
308 public void buildEnumConstantsDetails(List elements) throws Exception {
309 configuration.getBuilderFactory().
310 getEnumConstantsBuilder(writer).build(elements);
311 }
313 /**
314 * Build the field documentation.
315 *
316 * @param elements the XML elements that specify how a field is documented.
317 */
318 public void buildFieldDetails(List elements) throws Exception {
319 configuration.getBuilderFactory().
320 getFieldBuilder(writer).build(elements);
321 }
323 /**
324 * Build the constructor documentation.
325 *
326 * @param elements the XML elements that specify how to document a
327 * constructor.
328 */
329 public void buildConstructorDetails(List elements) throws Exception {
330 configuration.getBuilderFactory().
331 getConstructorBuilder(writer).build(elements);
332 }
334 /**
335 * Build the method documentation.
336 *
337 * @param elements the XML elements that specify how a method is documented.
338 */
339 public void buildMethodDetails(List elements) throws Exception {
340 configuration.getBuilderFactory().
341 getMethodBuilder(writer).build(elements);
342 }
344 /**
345 * Build the footer of the page.
346 */
347 public void buildClassFooter() {
348 writer.writeFooter();
349 }
350 }