Fri, 18 Jun 2010 21:13:56 -0700
6961178: Allow doclet.xml to contain XML attributes
Reviewed-by: bpatel
1 /*
2 * Copyright (c) 2003, 2008, 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 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.*;
34 /**
35 * Builds the summary for a given class.
36 *
37 * This code is not part of an API.
38 * It is implementation that is subject to change.
39 * Do not use it as an API
40 *
41 * @author Jamie Ho
42 * @since 1.5
43 */
44 public class ClassBuilder extends AbstractBuilder {
46 /**
47 * The root element of the class XML is {@value}.
48 */
49 public static final String ROOT = "ClassDoc";
51 /**
52 * The class being documented.
53 */
54 private ClassDoc classDoc;
56 /**
57 * The doclet specific writer.
58 */
59 private ClassWriter writer;
61 /**
62 * Keep track of whether or not this classdoc is an interface.
63 */
64 private boolean isInterface = false;
66 /**
67 * Keep track of whether or not this classdoc is an enum.
68 */
69 private boolean isEnum = false;
71 /**
72 * Construct a new ClassBuilder.
73 *
74 * @param configuration the current configuration of the
75 * doclet.
76 */
77 private ClassBuilder(Configuration configuration) {
78 super(configuration);
79 }
81 /**
82 * Construct a new ClassBuilder.
83 *
84 * @param configuration the current configuration of the doclet.
85 * @param classDoc the class being documented.
86 * @param writer the doclet specific writer.
87 */
88 public static ClassBuilder getInstance(Configuration configuration,
89 ClassDoc classDoc, ClassWriter writer)
90 throws Exception {
91 ClassBuilder builder = new ClassBuilder(configuration);
92 builder.configuration = configuration;
93 builder.classDoc = classDoc;
94 builder.writer = writer;
95 if (classDoc.isInterface()) {
96 builder.isInterface = true;
97 } else if (classDoc.isEnum()) {
98 builder.isEnum = true;
99 Util.setEnumDocumentation(configuration, classDoc);
100 }
101 if(containingPackagesSeen == null) {
102 containingPackagesSeen = new HashSet<String>();
103 }
104 return builder;
105 }
107 /**
108 * {@inheritDoc}
109 */
110 public void build() throws IOException {
111 build(LayoutParser.getInstance(configuration).parseXML(ROOT));
112 }
114 /**
115 * {@inheritDoc}
116 */
117 public String getName() {
118 return ROOT;
119 }
121 /**
122 * Handles the <ClassDoc> tag.
123 *
124 * @param elements the XML elements that specify how to document a class.
125 */
126 public void buildClassDoc(XMLNode node) throws Exception {
127 buildChildren(node);
128 writer.close();
129 copyDocFiles();
130 }
133 /**
134 * Copy the doc files for the current ClassDoc if necessary.
135 */
136 private void copyDocFiles() {
137 PackageDoc containingPackage = classDoc.containingPackage();
138 if((configuration.packages == null ||
139 Arrays.binarySearch(configuration.packages,
140 containingPackage) < 0) &&
141 ! containingPackagesSeen.contains(containingPackage.name())){
142 //Only copy doc files dir if the containing package is not
143 //documented AND if we have not documented a class from the same
144 //package already. Otherwise, we are making duplicate copies.
145 Util.copyDocFiles(configuration,
146 Util.getPackageSourcePath(configuration,
147 classDoc.containingPackage()) +
148 DirectoryManager.getDirectoryPath(classDoc.containingPackage())
149 + File.separator, DocletConstants.DOC_FILES_DIR_NAME, true);
150 containingPackagesSeen.add(containingPackage.name());
151 }
152 }
154 /**
155 * Build the header of the page.
156 */
157 public void buildClassHeader(XMLNode node) {
158 String key;
159 if (isInterface) {
160 key = "doclet.Interface";
161 } else if (isEnum) {
162 key = "doclet.Enum";
163 } else {
164 key = "doclet.Class";
165 }
167 writer.writeHeader(configuration.getText(key) + " " + classDoc.name());
168 }
170 /**
171 * Build the class tree documentation.
172 */
173 public void buildClassTree(XMLNode node) {
174 writer.writeClassTree();
175 }
177 /**
178 * If this is a class, list all interfaces
179 * implemented by this class.
180 */
181 public void buildImplementedInterfacesInfo(XMLNode node) {
182 writer.writeImplementedInterfacesInfo();
183 }
185 /**
186 * If this is an interface, list all super interfaces.
187 */
188 public void buildSuperInterfacesInfo(XMLNode node) {
189 writer.writeSuperInterfacesInfo();
190 }
192 /**
193 * List the parameters of this class.
194 */
195 public void buildTypeParamInfo(XMLNode node) {
196 writer.writeTypeParamInfo();
197 }
199 /**
200 * List all the classes extend this one.
201 */
202 public void buildSubClassInfo(XMLNode node) {
203 writer.writeSubClassInfo();
204 }
206 /**
207 * List all the interfaces that extend this one.
208 */
209 public void buildSubInterfacesInfo(XMLNode node) {
210 writer.writeSubInterfacesInfo();
211 }
213 /**
214 * If this is an interface, list all classes that implement this interface.
215 */
216 public void buildInterfaceUsageInfo (XMLNode node) {
217 writer.writeInterfaceUsageInfo();
218 }
220 /**
221 * If this is an inner class or interface, list the enclosing class or
222 * interface.
223 */
224 public void buildNestedClassInfo (XMLNode node) {
225 writer.writeNestedClassInfo();
226 }
228 /**
229 * If this class is deprecated, print the appropriate information.
230 */
231 public void buildDeprecationInfo (XMLNode node) {
232 writer.writeClassDeprecationInfo();
233 }
235 /**
236 * Build the signature of the current class.
237 */
238 public void buildClassSignature(XMLNode node) {
239 StringBuffer modifiers = new StringBuffer(classDoc.modifiers() + " ");
240 if (isEnum) {
241 modifiers.append("enum ");
242 int index;
243 if ((index = modifiers.indexOf("abstract")) >= 0) {
244 modifiers.delete(index, index + (new String("abstract")).length());
245 modifiers = new StringBuffer(
246 Util.replaceText(modifiers.toString(), " ", " "));
247 }
248 if ((index = modifiers.indexOf("final")) >= 0) {
249 modifiers.delete(index, index + (new String("final")).length());
250 modifiers = new StringBuffer(
251 Util.replaceText(modifiers.toString(), " ", " "));
252 }
253 //} else if (classDoc.isAnnotationType()) {
254 //modifiers.append("@interface ");
255 } else if (! isInterface) {
256 modifiers.append("class ");
257 }
258 writer.writeClassSignature(modifiers.toString());
259 }
261 /**
262 * Build the class description.
263 */
264 public void buildClassDescription(XMLNode node) {
265 writer.writeClassDescription();
266 }
268 /**
269 * Build the tag information for the current class.
270 */
271 public void buildClassTagInfo(XMLNode node) {
272 writer.writeClassTagInfo();
273 }
275 /**
276 * Build the contents of the page.
277 *
278 * @param elements the XML elements that specify how a member summary is
279 * documented.
280 */
281 public void buildMemberSummary(XMLNode node) throws Exception {
282 configuration.getBuilderFactory().
283 getMemberSummaryBuilder(writer).buildChildren(node);
284 writer.completeMemberSummaryBuild();
285 }
287 /**
288 * Build the enum constants documentation.
289 *
290 * @param elements the XML elements that specify how a enum constants are
291 * documented.
292 */
293 public void buildEnumConstantsDetails(XMLNode node) throws Exception {
294 configuration.getBuilderFactory().
295 getEnumConstantsBuilder(writer).buildChildren(node);
296 }
298 /**
299 * Build the field documentation.
300 *
301 * @param elements the XML elements that specify how a field is documented.
302 */
303 public void buildFieldDetails(XMLNode node) throws Exception {
304 configuration.getBuilderFactory().
305 getFieldBuilder(writer).buildChildren(node);
306 }
308 /**
309 * Build the constructor documentation.
310 *
311 * @param elements the XML elements that specify how to document a
312 * constructor.
313 */
314 public void buildConstructorDetails(XMLNode node) throws Exception {
315 configuration.getBuilderFactory().
316 getConstructorBuilder(writer).buildChildren(node);
317 }
319 /**
320 * Build the method documentation.
321 *
322 * @param elements the XML elements that specify how a method is documented.
323 */
324 public void buildMethodDetails(XMLNode node) throws Exception {
325 configuration.getBuilderFactory().
326 getMethodBuilder(writer).buildChildren(node);
327 }
329 /**
330 * Build the footer of the page.
331 */
332 public void buildClassFooter(XMLNode node) {
333 writer.writeFooter();
334 }
335 }