Wed, 31 Oct 2012 13:48:15 -0700
8001664: refactor javadoc to use abstraction to handle files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 2003, 2012, 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 java.io.*;
29 import java.util.*;
31 import com.sun.javadoc.*;
32 import com.sun.tools.doclets.internal.toolkit.*;
33 import com.sun.tools.doclets.internal.toolkit.util.*;
35 /**
36 * Builds the serialized form.
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 Jamie Ho
44 * @author Bhavesh Patel (Modified)
45 * @since 1.5
46 */
47 public class SerializedFormBuilder extends AbstractBuilder {
49 /**
50 * The root element of the serialized form XML is {@value}.
51 */
52 public static final String NAME = "SerializedForm";
54 /**
55 * The writer for this builder.
56 */
57 private SerializedFormWriter writer;
59 /**
60 * The writer for serializable fields.
61 */
62 private SerializedFormWriter.SerialFieldWriter fieldWriter;
64 /**
65 * The writer for serializable method documentation.
66 */
67 private SerializedFormWriter.SerialMethodWriter methodWriter;
69 /**
70 * The header for the serial version UID. Save the string
71 * here instead of the properties file because we do not want
72 * this string to be localized.
73 */
74 private static final String SERIAL_VERSION_UID_HEADER = "serialVersionUID:";
76 /**
77 * The current package being documented.
78 */
79 private PackageDoc currentPackage;
81 /**
82 * The current class being documented.
83 */
84 private ClassDoc currentClass;
86 /**
87 * The current member being documented.
88 */
89 protected MemberDoc currentMember;
91 /**
92 * The content that will be added to the serialized form documentation tree.
93 */
94 private Content contentTree;
96 private SerializedFormBuilder(Configuration configuration) {
97 super(configuration);
98 }
100 /**
101 * Construct a new SerializedFormBuilder.
102 * @param configuration the current configuration of the doclet.
103 */
104 public static SerializedFormBuilder getInstance(Configuration configuration) {
105 SerializedFormBuilder builder = new SerializedFormBuilder(configuration);
106 return builder;
107 }
109 /**
110 * Build the serialized form.
111 */
112 public void build() throws IOException {
113 if (! serialClassFoundToDocument(configuration.root.classes())) {
114 //Nothing to document.
115 return;
116 }
117 try {
118 writer = configuration.getWriterFactory().getSerializedFormWriter();
119 if (writer == null) {
120 //Doclet does not support this output.
121 return;
122 }
123 } catch (Exception e) {
124 throw new DocletAbortException();
125 }
126 build(LayoutParser.getInstance(configuration).parseXML(NAME), contentTree);
127 writer.close();
128 }
130 /**
131 * {@inheritDoc}
132 */
133 public String getName() {
134 return NAME;
135 }
137 /**
138 * Build the serialized form.
139 *
140 * @param node the XML element that specifies which components to document
141 * @param serializedTree content tree to which the documentation will be added
142 */
143 public void buildSerializedForm(XMLNode node, Content serializedTree) throws Exception {
144 serializedTree = writer.getHeader(configuration.getText(
145 "doclet.Serialized_Form"));
146 buildChildren(node, serializedTree);
147 writer.addFooter(serializedTree);
148 writer.printDocument(serializedTree);
149 writer.close();
150 }
152 /**
153 * Build the serialized form summaries.
154 *
155 * @param node the XML element that specifies which components to document
156 * @param serializedTree content tree to which the documentation will be added
157 */
158 public void buildSerializedFormSummaries(XMLNode node, Content serializedTree) {
159 Content serializedSummariesTree = writer.getSerializedSummariesHeader();
160 PackageDoc[] packages = configuration.packages;
161 for (int i = 0; i < packages.length; i++) {
162 currentPackage = packages[i];
163 buildChildren(node, serializedSummariesTree);
164 }
165 serializedTree.addContent(writer.getSerializedContent(
166 serializedSummariesTree));
167 }
169 /**
170 * Build the package serialized form for the current package being processed.
171 *
172 * @param node the XML element that specifies which components to document
173 * @param serializedSummariesTree content tree to which the documentation will be added
174 */
175 public void buildPackageSerializedForm(XMLNode node, Content serializedSummariesTree) {
176 Content packageSerializedTree = writer.getPackageSerializedHeader();
177 String foo = currentPackage.name();
178 ClassDoc[] classes = currentPackage.allClasses(false);
179 if (classes == null || classes.length == 0) {
180 return;
181 }
182 if (!serialInclude(currentPackage)) {
183 return;
184 }
185 if (!serialClassFoundToDocument(classes)) {
186 return;
187 }
188 buildChildren(node, packageSerializedTree);
189 serializedSummariesTree.addContent(packageSerializedTree);
190 }
192 /**
193 * Build the package header.
194 *
195 * @param node the XML element that specifies which components to document
196 * @param packageSerializedTree content tree to which the documentation will be added
197 */
198 public void buildPackageHeader(XMLNode node, Content packageSerializedTree) {
199 packageSerializedTree.addContent(writer.getPackageHeader(
200 Util.getPackageName(currentPackage)));
201 }
203 /**
204 * Build the class serialized form.
205 *
206 * @param node the XML element that specifies which components to document
207 * @param packageSerializedTree content tree to which the documentation will be added
208 */
209 public void buildClassSerializedForm(XMLNode node, Content packageSerializedTree) {
210 Content classSerializedTree = writer.getClassSerializedHeader();
211 ClassDoc[] classes = currentPackage.allClasses(false);
212 Arrays.sort(classes);
213 for (int j = 0; j < classes.length; j++) {
214 currentClass = classes[j];
215 fieldWriter = writer.getSerialFieldWriter(currentClass);
216 methodWriter = writer.getSerialMethodWriter(currentClass);
217 if(currentClass.isClass() && currentClass.isSerializable()) {
218 if(!serialClassInclude(currentClass)) {
219 continue;
220 }
221 Content classTree = writer.getClassHeader(currentClass);
222 buildChildren(node, classTree);
223 classSerializedTree.addContent(classTree);
224 }
225 }
226 packageSerializedTree.addContent(classSerializedTree);
227 }
229 /**
230 * Build the serial UID information for the given class.
231 *
232 * @param node the XML element that specifies which components to document
233 * @param classTree content tree to which the serial UID information will be added
234 */
235 public void buildSerialUIDInfo(XMLNode node, Content classTree) {
236 Content serialUidTree = writer.getSerialUIDInfoHeader();
237 FieldDoc[] fields = currentClass.fields(false);
238 for (int i = 0; i < fields.length; i++) {
239 if (fields[i].name().equals("serialVersionUID") &&
240 fields[i].constantValueExpression() != null) {
241 writer.addSerialUIDInfo(SERIAL_VERSION_UID_HEADER,
242 fields[i].constantValueExpression(), serialUidTree);
243 break;
244 }
245 }
246 classTree.addContent(serialUidTree);
247 }
249 /**
250 * Build the summaries for the methods and fields.
251 *
252 * @param node the XML element that specifies which components to document
253 * @param classTree content tree to which the documentation will be added
254 */
255 public void buildClassContent(XMLNode node, Content classTree) {
256 Content classContentTree = writer.getClassContentHeader();
257 buildChildren(node, classContentTree);
258 classTree.addContent(classContentTree);
259 }
261 /**
262 * Build the summaries for the methods that belong to the given
263 * class.
264 *
265 * @param node the XML element that specifies which components to document
266 * @param classContentTree content tree to which the documentation will be added
267 */
268 public void buildSerializableMethods(XMLNode node, Content classContentTree) {
269 Content serializableMethodTree = methodWriter.getSerializableMethodsHeader();
270 MemberDoc[] members = currentClass.serializationMethods();
271 int membersLength = members.length;
272 if (membersLength > 0) {
273 for (int i = 0; i < membersLength; i++) {
274 currentMember = members[i];
275 Content methodsContentTree = methodWriter.getMethodsContentHeader(
276 (i == membersLength - 1));
277 buildChildren(node, methodsContentTree);
278 serializableMethodTree.addContent(methodsContentTree);
279 }
280 }
281 if (currentClass.serializationMethods().length > 0) {
282 classContentTree.addContent(methodWriter.getSerializableMethods(
283 configuration.getText("doclet.Serialized_Form_methods"),
284 serializableMethodTree));
285 if (currentClass.isSerializable() && !currentClass.isExternalizable()) {
286 if (currentClass.serializationMethods().length == 0) {
287 Content noCustomizationMsg = methodWriter.getNoCustomizationMsg(
288 configuration.getText(
289 "doclet.Serializable_no_customization"));
290 classContentTree.addContent(methodWriter.getSerializableMethods(
291 configuration.getText("doclet.Serialized_Form_methods"),
292 noCustomizationMsg));
293 }
294 }
295 }
296 }
298 /**
299 * Build the method sub header.
300 *
301 * @param node the XML element that specifies which components to document
302 * @param methodsContentTree content tree to which the documentation will be added
303 */
304 public void buildMethodSubHeader(XMLNode node, Content methodsContentTree) {
305 methodWriter.addMemberHeader((MethodDoc)currentMember, methodsContentTree);
306 }
308 /**
309 * Build the deprecated method description.
310 *
311 * @param node the XML element that specifies which components to document
312 * @param methodsContentTree content tree to which the documentation will be added
313 */
314 public void buildDeprecatedMethodInfo(XMLNode node, Content methodsContentTree) {
315 methodWriter.addDeprecatedMemberInfo((MethodDoc) currentMember, methodsContentTree);
316 }
318 /**
319 * Build the information for the method.
320 *
321 * @param node the XML element that specifies which components to document
322 * @param methodsContentTree content tree to which the documentation will be added
323 */
324 public void buildMethodInfo(XMLNode node, Content methodsContentTree) {
325 if(configuration.nocomment){
326 return;
327 }
328 buildChildren(node, methodsContentTree);
329 }
331 /**
332 * Build method description.
333 *
334 * @param node the XML element that specifies which components to document
335 * @param methodsContentTree content tree to which the documentation will be added
336 */
337 public void buildMethodDescription(XMLNode node, Content methodsContentTree) {
338 methodWriter.addMemberDescription((MethodDoc) currentMember, methodsContentTree);
339 }
341 /**
342 * Build the method tags.
343 *
344 * @param node the XML element that specifies which components to document
345 * @param methodsContentTree content tree to which the documentation will be added
346 */
347 public void buildMethodTags(XMLNode node, Content methodsContentTree) {
348 methodWriter.addMemberTags((MethodDoc) currentMember, methodsContentTree);
349 MethodDoc method = (MethodDoc)currentMember;
350 if (method.name().compareTo("writeExternal") == 0
351 && method.tags("serialData").length == 0) {
352 if (configuration.serialwarn) {
353 configuration.getDocletSpecificMsg().warning(
354 currentMember.position(), "doclet.MissingSerialDataTag",
355 method.containingClass().qualifiedName(), method.name());
356 }
357 }
358 }
360 /**
361 * Build the field header.
362 *
363 * @param node the XML element that specifies which components to document
364 * @param classContentTree content tree to which the documentation will be added
365 */
366 public void buildFieldHeader(XMLNode node, Content classContentTree) {
367 if (currentClass.serializableFields().length > 0) {
368 buildFieldSerializationOverview(currentClass, classContentTree);
369 }
370 }
372 /**
373 * Build the serialization overview for the given class.
374 *
375 * @param classDoc the class to print the overview for.
376 * @param classContentTree content tree to which the documentation will be added
377 */
378 public void buildFieldSerializationOverview(ClassDoc classDoc, Content classContentTree) {
379 if (classDoc.definesSerializableFields()) {
380 FieldDoc serialPersistentField = classDoc.serializableFields()[0];
381 // Check to see if there are inline comments, tags or deprecation
382 // information to be printed.
383 if (fieldWriter.shouldPrintOverview(serialPersistentField)) {
384 Content serializableFieldsTree = fieldWriter.getSerializableFieldsHeader();
385 Content fieldsOverviewContentTree = fieldWriter.getFieldsContentHeader(true);
386 fieldWriter.addMemberDeprecatedInfo(serialPersistentField,
387 fieldsOverviewContentTree);
388 if (!configuration.nocomment) {
389 fieldWriter.addMemberDescription(serialPersistentField,
390 fieldsOverviewContentTree);
391 fieldWriter.addMemberTags(serialPersistentField,
392 fieldsOverviewContentTree);
393 }
394 serializableFieldsTree.addContent(fieldsOverviewContentTree);
395 classContentTree.addContent(fieldWriter.getSerializableFields(
396 configuration.getText("doclet.Serialized_Form_class"),
397 serializableFieldsTree));
398 }
399 }
400 }
402 /**
403 * Build the summaries for the fields that belong to the given class.
404 *
405 * @param node the XML element that specifies which components to document
406 * @param classContentTree content tree to which the documentation will be added
407 */
408 public void buildSerializableFields(XMLNode node, Content classContentTree) {
409 MemberDoc[] members = currentClass.serializableFields();
410 int membersLength = members.length;
411 if (membersLength > 0) {
412 Content serializableFieldsTree = fieldWriter.getSerializableFieldsHeader();
413 for (int i = 0; i < membersLength; i++) {
414 currentMember = members[i];
415 if (!currentClass.definesSerializableFields()) {
416 Content fieldsContentTree = fieldWriter.getFieldsContentHeader(
417 (i == membersLength - 1));
418 buildChildren(node, fieldsContentTree);
419 serializableFieldsTree.addContent(fieldsContentTree);
420 }
421 else {
422 buildSerialFieldTagsInfo(serializableFieldsTree);
423 }
424 }
425 classContentTree.addContent(fieldWriter.getSerializableFields(
426 configuration.getText("doclet.Serialized_Form_fields"),
427 serializableFieldsTree));
428 }
429 }
431 /**
432 * Build the field sub header.
433 *
434 * @param node the XML element that specifies which components to document
435 * @param fieldsContentTree content tree to which the documentation will be added
436 */
437 public void buildFieldSubHeader(XMLNode node, Content fieldsContentTree) {
438 if (!currentClass.definesSerializableFields()) {
439 FieldDoc field = (FieldDoc) currentMember;
440 fieldWriter.addMemberHeader(field.type().asClassDoc(),
441 field.type().typeName(), field.type().dimension(), field.name(),
442 fieldsContentTree);
443 }
444 }
446 /**
447 * Build the field deprecation information.
448 *
449 * @param node the XML element that specifies which components to document
450 * @param fieldsContentTree content tree to which the documentation will be added
451 */
452 public void buildFieldDeprecationInfo(XMLNode node, Content fieldsContentTree) {
453 if (!currentClass.definesSerializableFields()) {
454 FieldDoc field = (FieldDoc)currentMember;
455 fieldWriter.addMemberDeprecatedInfo(field, fieldsContentTree);
456 }
457 }
459 /**
460 * Build the serial field tags information.
461 *
462 * @param serializableFieldsTree content tree to which the documentation will be added
463 */
464 public void buildSerialFieldTagsInfo(Content serializableFieldsTree) {
465 if(configuration.nocomment){
466 return;
467 }
468 FieldDoc field = (FieldDoc)currentMember;
469 // Process Serializable Fields specified as array of
470 // ObjectStreamFields. Print a member for each serialField tag.
471 // (There should be one serialField tag per ObjectStreamField
472 // element.)
473 SerialFieldTag[] tags = field.serialFieldTags();
474 Arrays.sort(tags);
475 int tagsLength = tags.length;
476 for (int i = 0; i < tagsLength; i++) {
477 if (tags[i].fieldName() == null || tags[i].fieldType() == null) // ignore malformed @serialField tags
478 continue;
479 Content fieldsContentTree = fieldWriter.getFieldsContentHeader(
480 (i == tagsLength - 1));
481 fieldWriter.addMemberHeader(tags[i].fieldTypeDoc(),
482 tags[i].fieldType(), "", tags[i].fieldName(), fieldsContentTree);
483 fieldWriter.addMemberDescription(tags[i], fieldsContentTree);
484 serializableFieldsTree.addContent(fieldsContentTree);
485 }
486 }
488 /**
489 * Build the field information.
490 *
491 * @param node the XML element that specifies which components to document
492 * @param fieldsContentTree content tree to which the documentation will be added
493 */
494 public void buildFieldInfo(XMLNode node, Content fieldsContentTree) {
495 if(configuration.nocomment){
496 return;
497 }
498 FieldDoc field = (FieldDoc)currentMember;
499 ClassDoc cd = field.containingClass();
500 // Process default Serializable field.
501 if ((field.tags("serial").length == 0) && ! field.isSynthetic()
502 && configuration.serialwarn) {
503 configuration.message.warning(field.position(),
504 "doclet.MissingSerialTag", cd.qualifiedName(),
505 field.name());
506 }
507 fieldWriter.addMemberDescription(field, fieldsContentTree);
508 fieldWriter.addMemberTags(field, fieldsContentTree);
509 }
511 /**
512 * Return true if the given Doc should be included
513 * in the serialized form.
514 *
515 * @param doc the Doc object to check for serializability.
516 */
517 public static boolean serialInclude(Doc doc) {
518 if (doc == null) {
519 return false;
520 }
521 return doc.isClass() ?
522 serialClassInclude((ClassDoc)doc) :
523 serialDocInclude(doc);
524 }
526 /**
527 * Return true if the given ClassDoc should be included
528 * in the serialized form.
529 *
530 * @param cd the ClassDoc object to check for serializability.
531 */
532 private static boolean serialClassInclude(ClassDoc cd) {
533 if (cd.isEnum()) {
534 return false;
535 }
536 try {
537 cd.superclassType();
538 } catch (NullPointerException e) {
539 //Workaround for null pointer bug in ClassDoc.superclassType().
540 return false;
541 }
542 if (cd.isSerializable()) {
543 if (cd.tags("serial").length > 0) {
544 return serialDocInclude(cd);
545 } else if (cd.isPublic() || cd.isProtected()) {
546 return true;
547 } else {
548 return false;
549 }
550 }
551 return false;
552 }
554 /**
555 * Return true if the given Doc should be included
556 * in the serialized form.
557 *
558 * @param doc the Doc object to check for serializability.
559 */
560 private static boolean serialDocInclude(Doc doc) {
561 if (doc.isEnum()) {
562 return false;
563 }
564 Tag[] serial = doc.tags("serial");
565 if (serial.length > 0) {
566 String serialtext = serial[0].text().toLowerCase();
567 if (serialtext.indexOf("exclude") >= 0) {
568 return false;
569 } else if (serialtext.indexOf("include") >= 0) {
570 return true;
571 }
572 }
573 return true;
574 }
576 /**
577 * Return true if any of the given classes have a @serialinclude tag.
578 *
579 * @param classes the classes to check.
580 * @return true if any of the given classes have a @serialinclude tag.
581 */
582 private boolean serialClassFoundToDocument(ClassDoc[] classes) {
583 for (int i = 0; i < classes.length; i++) {
584 if (serialClassInclude(classes[i])) {
585 return true;
586 }
587 }
588 return false;
589 }
590 }