duke@1: /*
duke@1:  * Copyright 2003 Sun Microsystems, Inc.  All Rights Reserved.
duke@1:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1:  *
duke@1:  * This code is free software; you can redistribute it and/or modify it
duke@1:  * under the terms of the GNU General Public License version 2 only, as
duke@1:  * published by the Free Software Foundation.  Sun designates this
duke@1:  * particular file as subject to the "Classpath" exception as provided
duke@1:  * by Sun in the LICENSE file that accompanied this code.
duke@1:  *
duke@1:  * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
duke@1:  * version 2 for more details (a copy is included in the LICENSE file that
duke@1:  * accompanied this code).
duke@1:  *
duke@1:  * You should have received a copy of the GNU General Public License version
duke@1:  * 2 along with this work; if not, write to the Free Software Foundation,
duke@1:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1:  *
duke@1:  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@1:  * CA 95054 USA or visit www.sun.com if you need additional information or
duke@1:  * have any questions.
duke@1:  */
duke@1: 
duke@1: package com.sun.tools.doclets.internal.toolkit.builders;
duke@1: 
duke@1: import com.sun.tools.doclets.internal.toolkit.util.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.*;
duke@1: import com.sun.javadoc.*;
duke@1: import java.io.*;
duke@1: import java.lang.reflect.*;
duke@1: import java.util.*;
duke@1: 
duke@1: /**
duke@1:  * Builds the serialized form.
duke@1:  *
duke@1:  * This code is not part of an API.
duke@1:  * It is implementation that is subject to change.
duke@1:  * Do not use it as an API
duke@1:  *
duke@1:  * @author Jamie Ho
duke@1:  * @since 1.5
duke@1:  */
duke@1: public class SerializedFormBuilder extends AbstractBuilder {
duke@1: 
duke@1:     /**
duke@1:      * The root element of the serialized form XML is {@value}.
duke@1:      */
duke@1:     public static final String NAME = "SerializedForm";
duke@1: 
duke@1:     /**
duke@1:      * The writer for this builder.
duke@1:      */
duke@1:     private SerializedFormWriter writer;
duke@1: 
duke@1:     /**
duke@1:      * The writer for serializable fields.
duke@1:      */
duke@1:     private SerializedFormWriter.SerialFieldWriter fieldWriter;
duke@1: 
duke@1:     /**
duke@1:      * The writer for serializable method documentation.
duke@1:      */
duke@1:     private SerializedFormWriter.SerialMethodWriter methodWriter;
duke@1: 
duke@1:     /**
duke@1:      * The header for the serial version UID.  Save the string
duke@1:      * here instead of the properties file because we do not want
duke@1:      * this string to be localized.
duke@1:      */
duke@1:     private static final String SERIAL_VERSION_UID_HEADER = "serialVersionUID:";
duke@1: 
duke@1:     /**
duke@1:      * The current package being documented.
duke@1:      */
duke@1:     private PackageDoc currentPackage;
duke@1: 
duke@1:     /**
duke@1:      * The current class being documented.
duke@1:      */
duke@1:     private ClassDoc currentClass;
duke@1: 
duke@1:     /**
duke@1:      * The current member being documented.
duke@1:      */
duke@1:     protected MemberDoc currentMember;
duke@1: 
duke@1:     private SerializedFormBuilder(Configuration configuration) {
duke@1:         super(configuration);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Construct a new SerializedFormBuilder.
duke@1:      * @param configuration the current configuration of the doclet.
duke@1:      */
duke@1:     public static SerializedFormBuilder getInstance(Configuration configuration) {
duke@1:         SerializedFormBuilder builder = new SerializedFormBuilder(configuration);
duke@1:         return builder;
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the serialized form.
duke@1:      */
duke@1:     public void build() throws IOException {
duke@1:         if (! serialClassFoundToDocument(configuration.root.classes())) {
duke@1:             //Nothing to document.
duke@1:             return;
duke@1:         }
duke@1:         try {
duke@1:             writer = configuration.getWriterFactory().getSerializedFormWriter();
duke@1:             if (writer == null) {
duke@1:                 //Doclet does not support this output.
duke@1:                 return;
duke@1:             }
duke@1:         } catch (Exception e) {
duke@1:             throw new DocletAbortException();
duke@1:         }
duke@1:         build(LayoutParser.getInstance(configuration).parseXML(NAME));
duke@1:         writer.close();
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * {@inheritDoc}
duke@1:      */
duke@1:     public String getName() {
duke@1:         return NAME;
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the serialized form.
duke@1:      */
duke@1:     public void buildSerializedForm(List elements) throws Exception {
duke@1:         build(elements);
duke@1:         writer.close();
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * {@inheritDoc}
duke@1:      */
duke@1:     public void invokeMethod(String methodName, Class[] paramClasses,
duke@1:             Object[] params)
duke@1:     throws Exception {
duke@1:         if (DEBUG) {
duke@1:             configuration.root.printError("DEBUG: " + this.getClass().getName()
duke@1:                 + "." + methodName);
duke@1:         }
duke@1:         Method method = this.getClass().getMethod(methodName, paramClasses);
duke@1:         method.invoke(this, params);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the header.
duke@1:      */
duke@1:     public void buildHeader() {
duke@1:         writer.writeHeader(configuration.getText("doclet.Serialized_Form"));
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the contents.
duke@1:      */
duke@1:     public void buildSerializedFormSummaries(List elements) {
duke@1:         PackageDoc[] packages = configuration.packages;
duke@1:         for (int i = 0; i < packages.length; i++) {
duke@1:             currentPackage = packages[i];
duke@1:             build(elements);
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the package serialized for for the current package being processed.
duke@1:      */
duke@1:     public void buildPackageSerializedForm(List elements) {
duke@1:         String foo = currentPackage.name();
duke@1:         ClassDoc[] classes = currentPackage.allClasses(false);
duke@1:         if (classes == null || classes.length == 0) {
duke@1:             return;
duke@1:         }
duke@1:         if (!serialInclude(currentPackage)) {
duke@1:             return;
duke@1:         }
duke@1:         if (!serialClassFoundToDocument(classes)) {
duke@1:             return;
duke@1:         }
duke@1:         build(elements);
duke@1:     }
duke@1: 
duke@1:     public void buildPackageHeader() {
duke@1:         writer.writePackageHeader(Util.getPackageName(currentPackage));
duke@1:     }
duke@1: 
duke@1:     public void buildClassSerializedForm(List elements) {
duke@1:         ClassDoc[] classes = currentPackage.allClasses(false);
duke@1:         Arrays.sort(classes);
duke@1:         for (int j = 0; j < classes.length; j++) {
duke@1:             currentClass = classes[j];
duke@1:             fieldWriter = writer.getSerialFieldWriter(currentClass);
duke@1:             methodWriter = writer.getSerialMethodWriter(currentClass);
duke@1:             if(currentClass.isClass() && currentClass.isSerializable()) {
duke@1:                 if(!serialClassInclude(currentClass)) {
duke@1:                     continue;
duke@1:                 }
duke@1:                 build(elements);
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     public void buildClassHeader() {
duke@1:         writer.writeClassHeader(currentClass);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the serial UID information for the given class.
duke@1:      */
duke@1:     public void buildSerialUIDInfo() {
duke@1:         FieldDoc[] fields = currentClass.fields(false);
duke@1:         for (int i = 0; i < fields.length; i++) {
duke@1:             if (fields[i].name().equals("serialVersionUID") &&
duke@1:                 fields[i].constantValueExpression() != null) {
duke@1:                 writer.writeSerialUIDInfo(SERIAL_VERSION_UID_HEADER,
duke@1:                     fields[i].constantValueExpression());
duke@1:                 return;
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the footer.
duke@1:      */
duke@1:     public void buildFooter() {
duke@1:         writer.writeFooter();
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Return true if the given Doc should be included
duke@1:      * in the serialized form.
duke@1:      *
duke@1:      * @param doc the Doc object to check for serializability.
duke@1:      */
duke@1:     public static boolean serialInclude(Doc doc) {
duke@1:         if (doc == null) {
duke@1:             return false;
duke@1:         }
duke@1:         return doc.isClass() ?
duke@1:             serialClassInclude((ClassDoc)doc) :
duke@1:             serialDocInclude(doc);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Return true if the given ClassDoc should be included
duke@1:      * in the serialized form.
duke@1:      *
duke@1:      * @param cd the ClassDoc object to check for serializability.
duke@1:      */
duke@1:     private static boolean serialClassInclude(ClassDoc cd) {
duke@1:         if (cd.isEnum()) {
duke@1:             return false;
duke@1:         }
duke@1:         try {
duke@1:             cd.superclassType();
duke@1:         } catch (NullPointerException e) {
duke@1:             //Workaround for null pointer bug in ClassDoc.superclassType().
duke@1:             return false;
duke@1:         }
duke@1:         if (cd.isSerializable()) {
duke@1:             if (cd.tags("serial").length > 0) {
duke@1:                 return serialDocInclude(cd);
duke@1:             } else if (cd.isPublic() || cd.isProtected()) {
duke@1:                 return true;
duke@1:             } else {
duke@1:                 return false;
duke@1:             }
duke@1:         }
duke@1:         return false;
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Return true if the given Doc should be included
duke@1:      * in the serialized form.
duke@1:      *
duke@1:      * @param doc the Doc object to check for serializability.
duke@1:      */
duke@1:     private static boolean serialDocInclude(Doc doc) {
duke@1:         if (doc.isEnum()) {
duke@1:             return false;
duke@1:         }
duke@1:         Tag[] serial = doc.tags("serial");
duke@1:         if (serial.length > 0) {
duke@1:             String serialtext = serial[0].text().toLowerCase();
duke@1:             if (serialtext.indexOf("exclude") >= 0) {
duke@1:                 return false;
duke@1:             } else if (serialtext.indexOf("include") >= 0) {
duke@1:                 return true;
duke@1:             }
duke@1:         }
duke@1:         return true;
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Return true if any of the given classes have a @serialinclude tag.
duke@1:      *
duke@1:      * @param classes the classes to check.
duke@1:      * @return true if any of the given classes have a @serialinclude tag.
duke@1:      */
duke@1:     private boolean serialClassFoundToDocument(ClassDoc[] classes) {
duke@1:         for (int i = 0; i < classes.length; i++) {
duke@1:             if (serialClassInclude(classes[i])) {
duke@1:                 return true;
duke@1:             }
duke@1:         }
duke@1:         return false;
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the method header.
duke@1:      */
duke@1:     public void buildMethodHeader() {
duke@1:         if (currentClass.serializationMethods().length > 0) {
duke@1:             methodWriter.writeHeader(
duke@1:                 configuration.getText("doclet.Serialized_Form_methods"));
duke@1:             if (currentClass.isSerializable() && !currentClass.isExternalizable()) {
duke@1:                 if (currentClass.serializationMethods().length == 0) {
duke@1:                     methodWriter.writeNoCustomizationMsg(
duke@1:                         configuration.getText(
duke@1:                             "doclet.Serializable_no_customization"));
duke@1:                 }
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the method sub header.
duke@1:      */
duke@1:     public void buildMethodSubHeader()  {
duke@1:         methodWriter.writeMemberHeader((MethodDoc) currentMember);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the deprecated method description.
duke@1:      */
duke@1:     public void buildDeprecatedMethodInfo() {
duke@1:         methodWriter.writeDeprecatedMemberInfo((MethodDoc) currentMember);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build method tags.
duke@1:      */
duke@1:     public void buildMethodDescription() {
duke@1:         methodWriter.writeMemberDescription((MethodDoc) currentMember);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the method tags.
duke@1:      */
duke@1:     public void buildMethodTags() {
duke@1:         methodWriter.writeMemberTags((MethodDoc) currentMember);
duke@1:         MethodDoc method = (MethodDoc)currentMember;
duke@1:         if (method.name().compareTo("writeExternal") == 0
duke@1:             && method.tags("serialData").length == 0) {
duke@1:             if (configuration.serialwarn) {
duke@1:                 configuration.getDocletSpecificMsg().warning(
duke@1:                     currentMember.position(), "doclet.MissingSerialDataTag",
duke@1:                     method.containingClass().qualifiedName(), method.name());
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * build the information for the method.
duke@1:      */
duke@1:     public void buildMethodInfo(List elements)  {
duke@1:         if(configuration.nocomment){
duke@1:             return;
duke@1:         }
duke@1:         build(elements);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the method footer.
duke@1:      */
duke@1:     public void buildMethodFooter() {
duke@1:         methodWriter.writeMemberFooter((MethodDoc) currentMember);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the field header.
duke@1:      */
duke@1:     public void buildFieldHeader() {
duke@1:         if (currentClass.serializableFields().length > 0) {
duke@1:             buildFieldSerializationOverview(currentClass);
duke@1:             fieldWriter.writeHeader(configuration.getText(
duke@1:                 "doclet.Serialized_Form_fields"));
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * If possible, build the serialization overview for the given
duke@1:      * class.
duke@1:      *
duke@1:      * @param classDoc the class to print the overview for.
duke@1:      */
duke@1:     public void buildFieldSerializationOverview(ClassDoc classDoc) {
duke@1:         if (classDoc.definesSerializableFields()) {
duke@1:             FieldDoc serialPersistentField =
duke@1:                 (FieldDoc)((Util.asList(classDoc.serializableFields()).get(0)));
duke@1:             String comment = serialPersistentField.commentText();
duke@1:             if (comment.length() > 0) {
duke@1:                 fieldWriter.writeHeader(
duke@1:                     configuration.getText("doclet.Serialized_Form_class"));
duke@1:                 if (!configuration.nocomment) {
duke@1:                     fieldWriter.writeMemberDeprecatedInfo(serialPersistentField);
duke@1:                     fieldWriter.writeMemberDescription(serialPersistentField);
duke@1:                     fieldWriter.writeMemberTags(serialPersistentField);
duke@1:                     fieldWriter.writeMemberFooter(serialPersistentField);
duke@1:                 }
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the field sub header.
duke@1:      */
duke@1:     public void buildFieldSubHeader() {
duke@1:         if (! currentClass.definesSerializableFields() ){
duke@1:             FieldDoc field = (FieldDoc) currentMember;
duke@1:             fieldWriter.writeMemberHeader(field.type().asClassDoc(),
duke@1:                 field.type().typeName(), field.type().dimension(), field.name());
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the field information.
duke@1:      */
duke@1:     public void buildFieldInfo() {
duke@1:         if(configuration.nocomment){
duke@1:             return;
duke@1:         }
duke@1:         FieldDoc field = (FieldDoc)currentMember;
duke@1:         ClassDoc cd = field.containingClass();
duke@1:         if (cd.definesSerializableFields()) {
duke@1:             // Process Serializable Fields specified as array of
duke@1:             // ObjectStreamFields. Print a member for each serialField tag.
duke@1:             // (There should be one serialField tag per ObjectStreamField
duke@1:             // element.)
duke@1:             SerialFieldTag[] tags = field.serialFieldTags();
duke@1:             Arrays.sort(tags);
duke@1:             for (int i = 0; i < tags.length; i++) {
duke@1:                 fieldWriter.writeMemberHeader(tags[i].fieldTypeDoc(),
duke@1:                         tags[i].fieldType(), "", tags[i].fieldName());
duke@1:                 fieldWriter.writeMemberDescription(tags[i]);
duke@1: 
duke@1:             }
duke@1:         } else {
duke@1: 
duke@1:             // Process default Serializable field.
duke@1:             if ((field.tags("serial").length == 0) && ! field.isSynthetic()
duke@1:                 && configuration.serialwarn) {
duke@1:                 configuration.message.warning(field.position(),
duke@1:                         "doclet.MissingSerialTag", cd.qualifiedName(),
duke@1:                         field.name());
duke@1:             }
duke@1:             fieldWriter.writeMemberDeprecatedInfo(field);
duke@1:             fieldWriter.writeMemberDescription(field);
duke@1:             fieldWriter.writeMemberTags(field);
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the field footer.
duke@1:      */
duke@1:     public void buildFieldFooter() {
duke@1:         if (! currentClass.definesSerializableFields()) {
duke@1:             fieldWriter.writeMemberFooter((FieldDoc) currentMember);
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the summaries for the methods that belong to the given
duke@1:      * class.
duke@1:      */
duke@1:     public void buildSerializableMethods(List elements) {
duke@1:         MemberDoc[] members = currentClass.serializationMethods();
duke@1:         if (members.length > 0) {
duke@1:             for (int i = 0; i < members.length; i++) {
duke@1:                 currentMember = members[i];
duke@1:                 build(elements);
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Build the summaries for the fields that belong to the given
duke@1:      * class.
duke@1:      */
duke@1:     public void buildSerializableFields(List elements) {
duke@1:         MemberDoc[] members = currentClass.serializableFields();
duke@1:         if (members.length > 0) {
duke@1:             for (int i = 0; i < members.length; i++) {
duke@1:                 currentMember = members[i];
duke@1:                 build(elements);
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: }