Mercurial > jdk8-mips64-public > langtools / file revision

 /*

  * Copyright 2003-2009 Sun Microsystems, Inc.  All Rights Reserved.

  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  *

  * This code is free software; you can redistribute it and/or modify it

  * under the terms of the GNU General Public License version 2 only, as

  * published by the Free Software Foundation.  Sun designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Sun in the LICENSE file that accompanied this code.

  *

  * This code is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

  * version 2 for more details (a copy is included in the LICENSE file that

  * accompanied this code).

  *

  * You should have received a copy of the GNU General Public License version

  * 2 along with this work; if not, write to the Free Software Foundation,

  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  *

  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

  * CA 95054 USA or visit www.sun.com if you need additional information or

  * have any questions.

  */

 package com.sun.tools.doclets.internal.toolkit.builders;

 import java.io.*;

 import java.lang.reflect.*;

 import java.util.*;

 import com.sun.javadoc.*;

 import com.sun.tools.doclets.internal.toolkit.util.*;

 import com.sun.tools.doclets.internal.toolkit.*;

 /**

  * Builds the serialized form.

  *

  * This code is not part of an API.

  * It is implementation that is subject to change.

  * Do not use it as an API

  *

  * @author Jamie Ho

  * @author Bhavesh Patel (Modified)

  * @since 1.5

  */

 public class SerializedFormBuilder extends AbstractBuilder {

     /**

      * The root element of the serialized form XML is {@value}.

      */

     public static final String NAME = "SerializedForm";

     /**

      * The writer for this builder.

      */

     private SerializedFormWriter writer;

     /**

      * The writer for serializable fields.

      */

     private SerializedFormWriter.SerialFieldWriter fieldWriter;

     /**

      * The writer for serializable method documentation.

      */

     private SerializedFormWriter.SerialMethodWriter methodWriter;

     /**

      * The header for the serial version UID.  Save the string

      * here instead of the properties file because we do not want

      * this string to be localized.

      */

     private static final String SERIAL_VERSION_UID_HEADER = "serialVersionUID:";

     /**

      * The current package being documented.

      */

     private PackageDoc currentPackage;

     /**

      * The current class being documented.

      */

     private ClassDoc currentClass;

     /**

      * The current member being documented.

      */

     protected MemberDoc currentMember;

     private SerializedFormBuilder(Configuration configuration) {

         super(configuration);

     }

     /**

      * Construct a new SerializedFormBuilder.

      * @param configuration the current configuration of the doclet.

      */

     public static SerializedFormBuilder getInstance(Configuration configuration) {

         SerializedFormBuilder builder = new SerializedFormBuilder(configuration);

         return builder;

     }

     /**

      * Build the serialized form.

      */

     public void build() throws IOException {

         if (! serialClassFoundToDocument(configuration.root.classes())) {

             //Nothing to document.

             return;

         }

         try {

             writer = configuration.getWriterFactory().getSerializedFormWriter();

             if (writer == null) {

                 //Doclet does not support this output.

                 return;

             }

         } catch (Exception e) {

             throw new DocletAbortException();

         }

         build(LayoutParser.getInstance(configuration).parseXML(NAME));

         writer.close();

     }

     /**

      * {@inheritDoc}

      */

     public String getName() {

         return NAME;

     }

     /**

      * Build the serialized form.

      */

     public void buildSerializedForm(List<?> elements) throws Exception {

         build(elements);

         writer.close();

     }

     /**

      * {@inheritDoc}

      */

     public void invokeMethod(String methodName, Class<?>[] paramClasses,

             Object[] params)

     throws Exception {

         if (DEBUG) {

             configuration.root.printError("DEBUG: " + this.getClass().getName()

                 + "." + methodName);

         }

         Method method = this.getClass().getMethod(methodName, paramClasses);

         method.invoke(this, params);

     }

     /**

      * Build the header.

      */

     public void buildHeader() {

         writer.writeHeader(configuration.getText("doclet.Serialized_Form"));

     }

     /**

      * Build the contents.

      */

     public void buildSerializedFormSummaries(List<?> elements) {

         PackageDoc[] packages = configuration.packages;

         for (int i = 0; i < packages.length; i++) {

             currentPackage = packages[i];

             build(elements);

         }

     }

     /**

      * Build the package serialized for for the current package being processed.

      */

     public void buildPackageSerializedForm(List<?> elements) {

         String foo = currentPackage.name();

         ClassDoc[] classes = currentPackage.allClasses(false);

         if (classes == null || classes.length == 0) {

             return;

         }

         if (!serialInclude(currentPackage)) {

             return;

         }

         if (!serialClassFoundToDocument(classes)) {

             return;

         }

         build(elements);

     }

     public void buildPackageHeader() {

         writer.writePackageHeader(Util.getPackageName(currentPackage));

     }

     public void buildClassSerializedForm(List<?> elements) {

         ClassDoc[] classes = currentPackage.allClasses(false);

         Arrays.sort(classes);

         for (int j = 0; j < classes.length; j++) {

             currentClass = classes[j];

             fieldWriter = writer.getSerialFieldWriter(currentClass);

             methodWriter = writer.getSerialMethodWriter(currentClass);

             if(currentClass.isClass() && currentClass.isSerializable()) {

                 if(!serialClassInclude(currentClass)) {

                     continue;

                 }

                 build(elements);

             }

         }

     }

     public void buildClassHeader() {

         writer.writeClassHeader(currentClass);

     }

     /**

      * Build the serial UID information for the given class.

      */

     public void buildSerialUIDInfo() {

         FieldDoc[] fields = currentClass.fields(false);

         for (int i = 0; i < fields.length; i++) {

             if (fields[i].name().equals("serialVersionUID") &&

                 fields[i].constantValueExpression() != null) {

                 writer.writeSerialUIDInfo(SERIAL_VERSION_UID_HEADER,

                     fields[i].constantValueExpression());

                 return;

             }

         }

     }

     /**

      * Build the footer.

      */

     public void buildFooter() {

         writer.writeFooter();

     }

     /**

      * Return true if the given Doc should be included

      * in the serialized form.

      *

      * @param doc the Doc object to check for serializability.

      */

     public static boolean serialInclude(Doc doc) {

         if (doc == null) {

             return false;

         }

         return doc.isClass() ?

             serialClassInclude((ClassDoc)doc) :

             serialDocInclude(doc);

     }

     /**

      * Return true if the given ClassDoc should be included

      * in the serialized form.

      *

      * @param cd the ClassDoc object to check for serializability.

      */

     private static boolean serialClassInclude(ClassDoc cd) {

         if (cd.isEnum()) {

             return false;

         }

         try {

             cd.superclassType();

         } catch (NullPointerException e) {

             //Workaround for null pointer bug in ClassDoc.superclassType().

             return false;

         }

         if (cd.isSerializable()) {

             if (cd.tags("serial").length > 0) {

                 return serialDocInclude(cd);

             } else if (cd.isPublic() || cd.isProtected()) {

                 return true;

             } else {

                 return false;

             }

         }

         return false;

     }

     /**

      * Return true if the given Doc should be included

      * in the serialized form.

      *

      * @param doc the Doc object to check for serializability.

      */

     private static boolean serialDocInclude(Doc doc) {

         if (doc.isEnum()) {

             return false;

         }

         Tag[] serial = doc.tags("serial");

         if (serial.length > 0) {

             String serialtext = serial[0].text().toLowerCase();

             if (serialtext.indexOf("exclude") >= 0) {

                 return false;

             } else if (serialtext.indexOf("include") >= 0) {

                 return true;

             }

         }

         return true;

     }

     /**

      * Return true if any of the given classes have a @serialinclude tag.

      *

      * @param classes the classes to check.

      * @return true if any of the given classes have a @serialinclude tag.

      */

     private boolean serialClassFoundToDocument(ClassDoc[] classes) {

         for (int i = 0; i < classes.length; i++) {

             if (serialClassInclude(classes[i])) {

                 return true;

             }

         }

         return false;

     }

     /**

      * Build the method header.

      */

     public void buildMethodHeader() {

         if (currentClass.serializationMethods().length > 0) {

             methodWriter.writeHeader(

                 configuration.getText("doclet.Serialized_Form_methods"));

             if (currentClass.isSerializable() && !currentClass.isExternalizable()) {

                 if (currentClass.serializationMethods().length == 0) {

                     methodWriter.writeNoCustomizationMsg(

                         configuration.getText(

                             "doclet.Serializable_no_customization"));

                 }

             }

         }

     }

     /**

      * Build the method sub header.

      */

     public void buildMethodSubHeader()  {

         methodWriter.writeMemberHeader((MethodDoc) currentMember);

     }

     /**

      * Build the deprecated method description.

      */

     public void buildDeprecatedMethodInfo() {

         methodWriter.writeDeprecatedMemberInfo((MethodDoc) currentMember);

     }

     /**

      * Build method tags.

      */

     public void buildMethodDescription() {

         methodWriter.writeMemberDescription((MethodDoc) currentMember);

     }

     /**

      * Build the method tags.

      */

     public void buildMethodTags() {

         methodWriter.writeMemberTags((MethodDoc) currentMember);

         MethodDoc method = (MethodDoc)currentMember;

         if (method.name().compareTo("writeExternal") == 0

             && method.tags("serialData").length == 0) {

             if (configuration.serialwarn) {

                 configuration.getDocletSpecificMsg().warning(

                     currentMember.position(), "doclet.MissingSerialDataTag",

                     method.containingClass().qualifiedName(), method.name());

             }

         }

     }

     /**

      * build the information for the method.

      */

     public void buildMethodInfo(List<?> elements)  {

         if(configuration.nocomment){

             return;

         }

         build(elements);

     }

     /**

      * Build the method footer.

      */

     public void buildMethodFooter() {

         methodWriter.writeMemberFooter();

     }

     /**

      * Build the field header.

      */

     public void buildFieldHeader() {

         if (currentClass.serializableFields().length > 0) {

             buildFieldSerializationOverview(currentClass);

             fieldWriter.writeHeader(configuration.getText(

                 "doclet.Serialized_Form_fields"));

         }

     }

     /**

      * If possible, build the serialization overview for the given

      * class.

      *

      * @param classDoc the class to print the overview for.

      */

     public void buildFieldSerializationOverview(ClassDoc classDoc) {

         if (classDoc.definesSerializableFields()) {

             FieldDoc serialPersistentField =

                 Util.asList(classDoc.serializableFields()).get(0);

             // Check to see if there are inline comments, tags or deprecation

             // information to be printed.

             if (fieldWriter.shouldPrintOverview(serialPersistentField)) {

                 fieldWriter.writeHeader(

                         configuration.getText("doclet.Serialized_Form_class"));

                 fieldWriter.writeMemberDeprecatedInfo(serialPersistentField);

                 if (!configuration.nocomment) {

                     fieldWriter.writeMemberDescription(serialPersistentField);

                     fieldWriter.writeMemberTags(serialPersistentField);

                 }

                 // Footer required to close the definition list tag

                 // for serialization overview.

                 fieldWriter.writeFooter(

                         configuration.getText("doclet.Serialized_Form_class"));

             }

         }

     }

     /**

      * Build the field sub header.

      */

     public void buildFieldSubHeader() {

         if (! currentClass.definesSerializableFields() ){

             FieldDoc field = (FieldDoc) currentMember;

             fieldWriter.writeMemberHeader(field.type().asClassDoc(),

                 field.type().typeName(), field.type().dimension(), field.name());

         }

     }

     /**

      * Build the field deprecation information.

      */

     public void buildFieldDeprecationInfo() {

         if (!currentClass.definesSerializableFields()) {

             FieldDoc field = (FieldDoc)currentMember;

             fieldWriter.writeMemberDeprecatedInfo(field);

         }

     }

     /**

      * Build the field information.

      */

     public void buildFieldInfo() {

         if(configuration.nocomment){

             return;

         }

         FieldDoc field = (FieldDoc)currentMember;

         ClassDoc cd = field.containingClass();

         if (cd.definesSerializableFields()) {

             // Process Serializable Fields specified as array of

             // ObjectStreamFields. Print a member for each serialField tag.

             // (There should be one serialField tag per ObjectStreamField

             // element.)

             SerialFieldTag[] tags = field.serialFieldTags();

             Arrays.sort(tags);

             for (int i = 0; i < tags.length; i++) {

                 fieldWriter.writeMemberHeader(tags[i].fieldTypeDoc(),

                         tags[i].fieldType(), "", tags[i].fieldName());

                 fieldWriter.writeMemberDescription(tags[i]);

             }

         } else {

             // Process default Serializable field.

             if ((field.tags("serial").length == 0) && ! field.isSynthetic()

                 && configuration.serialwarn) {

                 configuration.message.warning(field.position(),

                         "doclet.MissingSerialTag", cd.qualifiedName(),

                         field.name());

             }

             fieldWriter.writeMemberDescription(field);

             fieldWriter.writeMemberTags(field);

         }

     }

     /**

      * Build the field sub footer.

      */

     public void buildFieldSubFooter() {

         if (! currentClass.definesSerializableFields()) {

             fieldWriter.writeMemberFooter();

         }

     }

     /**

      * Build the summaries for the methods that belong to the given

      * class.

      */

     public void buildSerializableMethods(List<?> elements) {

         MemberDoc[] members = currentClass.serializationMethods();

         if (members.length > 0) {

             for (int i = 0; i < members.length; i++) {

                 currentMember = members[i];

                 build(elements);

             }

         }

     }

     /**

      * Build the summaries for the fields that belong to the given

      * class.

      */

     public void buildSerializableFields(List<?> elements) {

         MemberDoc[] members = currentClass.serializableFields();

         if (members.length > 0) {

             for (int i = 0; i < members.length; i++) {

                 currentMember = members[i];

                 build(elements);

             }

         }

     }

 }