jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/javadoc/SerializedForm.java@25e14ad23cef (annotated)

src/share/classes/com/sun/tools/javadoc/SerializedForm.java@25e14ad23cef (annotated)

src/share/classes/com/sun/tools/javadoc/SerializedForm.java

Wed, 10 Oct 2012 16:48:21 -0700

author: jjg
date: Wed, 10 Oct 2012 16:48:21 -0700
changeset 1359: 25e14ad23cef
parent 1357: c75be5bc5283
child 1372: 78962d89f283
permissions: -rw-r--r--

8000665: fix "internal API" comments on javadoc files
Reviewed-by: darcy

 /*
  * Copyright (c) 1998, 2012, Oracle and/or its affiliates. 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.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 package com.sun.tools.javadoc;
 import com.sun.javadoc.*;
 import com.sun.tools.javac.code.Flags;
 import com.sun.tools.javac.code.Kinds;
 import com.sun.tools.javac.code.Scope;
 import com.sun.tools.javac.code.Symbol.ClassSymbol;
 import com.sun.tools.javac.code.Symbol.MethodSymbol;
 import com.sun.tools.javac.code.Symbol.VarSymbol;
 import com.sun.tools.javac.util.ListBuffer;
 import com.sun.tools.javac.util.Name;
 import com.sun.tools.javac.util.Names;
 /**
  * The serialized form is the specification of a class' serialization
  * state. <p>
  *
  * It consists of the following information:<p>
  *
  * <pre>
  * 1. Whether class is Serializable or Externalizable.
  * 2. Javadoc for serialization methods.
  *    a. For Serializable, the optional readObject, writeObject,
  *       readResolve and writeReplace.
  *       serialData tag describes, in prose, the sequence and type
  *       of optional data written by writeObject.
  *    b. For Externalizable, writeExternal and readExternal.
  *       serialData tag describes, in prose, the sequence and type
  *       of optional data written by writeExternal.
  * 3. Javadoc for serialization data layout.
  *    a. For Serializable, the name,type and description
  *       of each Serializable fields.
  *    b. For Externalizable, data layout is described by 2(b).
  * </pre>
  *
  *  <p><b>This is NOT part of any supported API.
  *  If you write code that depends on this, you do so at your own risk.
  *  This code and its internal interfaces are subject to change or
  *  deletion without notice.</b>
  *
  * @since 1.2
  * @author Joe Fialli
  * @author Neal Gafter (rewrite but not too proud)
  */
 class SerializedForm {
     ListBuffer<MethodDoc> methods = new ListBuffer<MethodDoc>();
     /* List of FieldDocImpl - Serializable fields.
      * Singleton list if class defines Serializable fields explicitly.
      * Otherwise, list of default serializable fields.
      * 0 length list for Externalizable.
      */
     private final ListBuffer<FieldDocImpl> fields = new ListBuffer<FieldDocImpl>();
     /* True if class specifies serializable fields explicitly.
      * using special static member, serialPersistentFields.
      */
     private boolean definesSerializableFields = false;
     // Specially treated field/method names defined by Serialization.
     private static final String SERIALIZABLE_FIELDS = "serialPersistentFields";
     private static final String READOBJECT  = "readObject";
     private static final String WRITEOBJECT = "writeObject";
     private static final String READRESOLVE  = "readResolve";
     private static final String WRITEREPLACE = "writeReplace";
     private static final String READOBJECTNODATA = "readObjectNoData";
     /**
      * Constructor.
      *
      * Catalog Serializable fields for Serializable class.
      * Catalog serialization methods for Serializable and
      * Externalizable classes.
      */
     SerializedForm(DocEnv env, ClassSymbol def, ClassDocImpl cd) {
         if (cd.isExternalizable()) {
             /* look up required public accessible methods,
              *   writeExternal and readExternal.
              */
             String[] readExternalParamArr = { "java.io.ObjectInput" };
             String[] writeExternalParamArr = { "java.io.ObjectOutput" };
             MethodDoc md = cd.findMethod("readExternal", readExternalParamArr);
             if (md != null) {
                 methods.append(md);
             }
             md = cd.findMethod("writeExternal", writeExternalParamArr);
             if (md != null) {
                 methods.append(md);
                 Tag tag[] = md.tags("serialData");
             }
         // } else { // isSerializable() //### ???
         } else if (cd.isSerializable()) {
             VarSymbol dsf = getDefinedSerializableFields(def);
             if (dsf != null) {
                 /* Define serializable fields with array of ObjectStreamField.
                  * Each ObjectStreamField should be documented by a
                  * serialField tag.
                  */
                 definesSerializableFields = true;
                 //### No modifier filtering applied here.
                 FieldDocImpl dsfDoc = env.getFieldDoc(dsf);
                 fields.append(dsfDoc);
                 mapSerialFieldTagImplsToFieldDocImpls(dsfDoc, env, def);
             } else {
                 /* Calculate default Serializable fields as all
                  * non-transient, non-static fields.
                  * Fields should be documented by serial tag.
                  */
                 computeDefaultSerializableFields(env, def, cd);
             }
            /* Check for optional customized readObject, writeObject,
             * readResolve and writeReplace, which can all contain
             * the serialData tag.        */
             addMethodIfExist(env, def, READOBJECT);
             addMethodIfExist(env, def, WRITEOBJECT);
             addMethodIfExist(env, def, READRESOLVE);
             addMethodIfExist(env, def, WRITEREPLACE);
             addMethodIfExist(env, def, READOBJECTNODATA);
         }
     }
     /*
      * Check for explicit Serializable fields.
      * Check for a private static array of ObjectStreamField with
      * name SERIALIZABLE_FIELDS.
      */
     private VarSymbol getDefinedSerializableFields(ClassSymbol def) {
         Names names = def.name.table.names;
         /* SERIALIZABLE_FIELDS can be private,
          * so must lookup by ClassSymbol, not by ClassDocImpl.
          */
         for (Scope.Entry e = def.members().lookup(names.fromString(SERIALIZABLE_FIELDS)); e.scope != null; e = e.next()) {
             if (e.sym.kind == Kinds.VAR) {
                 VarSymbol f = (VarSymbol)e.sym;
                 if ((f.flags() & Flags.STATIC) != 0 &&
                     (f.flags() & Flags.PRIVATE) != 0) {
                     return f;
                 }
             }
         }
         return null;
     }
     /*
      * Compute default Serializable fields from all members of ClassSymbol.
      *
      * Since the fields of ClassDocImpl might not contain private or
      * package accessible fields, must walk over all members of ClassSymbol.
      */
     private void computeDefaultSerializableFields(DocEnv env,
                                                   ClassSymbol def,
                                                   ClassDocImpl cd) {
         for (Scope.Entry e = def.members().elems; e != null; e = e.sibling) {
             if (e.sym != null && e.sym.kind == Kinds.VAR) {
                 VarSymbol f = (VarSymbol)e.sym;
                 if ((f.flags() & Flags.STATIC) == 0 &&
                     (f.flags() & Flags.TRANSIENT) == 0) {
                     //### No modifier filtering applied here.
                     FieldDocImpl fd = env.getFieldDoc(f);
                     //### Add to beginning.
                     //### Preserve order used by old 'javadoc'.
                     fields.prepend(fd);
                 }
             }
         }
     }
     /*
      * Catalog Serializable method if it exists in current ClassSymbol.
      * Do not look for method in superclasses.
      *
      * Serialization requires these methods to be non-static.
      *
      * @param method should be an unqualified Serializable method
      *               name either READOBJECT, WRITEOBJECT, READRESOLVE
      *               or WRITEREPLACE.
      * @param visibility the visibility flag for the given method.
      */
     private void addMethodIfExist(DocEnv env, ClassSymbol def, String methodName) {
         Names names = def.name.table.names;
         for (Scope.Entry e = def.members().lookup(names.fromString(methodName)); e.scope != null; e = e.next()) {
             if (e.sym.kind == Kinds.MTH) {
                 MethodSymbol md = (MethodSymbol)e.sym;
                 if ((md.flags() & Flags.STATIC) == 0) {
                     /*
                      * WARNING: not robust if unqualifiedMethodName is overloaded
                      *          method. Signature checking could make more robust.
                      * READOBJECT takes a single parameter, java.io.ObjectInputStream.
                      * WRITEOBJECT takes a single parameter, java.io.ObjectOutputStream.
                      */
                     methods.append(env.getMethodDoc(md));
                 }
             }
         }
     }
     /*
      * Associate serialField tag fieldName with FieldDocImpl member.
      * Note: A serialField tag does not have to map an existing field
      *       of a class.
      */
     private void mapSerialFieldTagImplsToFieldDocImpls(FieldDocImpl spfDoc,
                                                        DocEnv env,
                                                        ClassSymbol def) {
         Names names = def.name.table.names;
         SerialFieldTag[] sfTag = spfDoc.serialFieldTags();
         for (int i = 0; i < sfTag.length; i++) {
             Name fieldName = names.fromString(sfTag[i].fieldName());
             // Look for a FieldDocImpl that is documented by serialFieldTagImpl.
             for (Scope.Entry e = def.members().lookup(fieldName); e.scope != null; e = e.next()) {
                 if (e.sym.kind == Kinds.VAR) {
                     VarSymbol f = (VarSymbol)e.sym;
                     FieldDocImpl fdi = env.getFieldDoc(f);
                     ((SerialFieldTagImpl)(sfTag[i])).mapToFieldDocImpl(fdi);
                     break;
                 }
             }
         }
     }
     /**
      * Return serializable fields in class. <p>
      *
      * Returns either a list of default fields documented by serial tag comment or
      *         javadoc comment<p>
      * Or Returns a single FieldDocImpl for serialPersistentField. There is a
      *         serialField tag for each serializable field.<p>
      *
      * @return an array of FieldDocImpl for representing the visible
      *         fields in this class.
      */
     FieldDoc[] fields() {
         return (FieldDoc[])fields.toArray(new FieldDocImpl[fields.length()]);
     }
     /**
      * Return serialization methods in class.
      *
      * @return an array of MethodDocImpl for serialization methods in this class.
      */
     MethodDoc[] methods() {
         return methods.toArray(new MethodDoc[methods.length()]);
     }
     /**
      * Returns true if Serializable fields are defined explicitly using
      * member, serialPersistentFields.
      *
      * @see #fields()
      */
     boolean definesSerializableFields() {
         return definesSerializableFields;
     }
 }

Mercurial > jdk8-mips64-public > langtools / annotate

src/share/classes/com/sun/tools/javadoc/SerializedForm.java@25e14ad23cef (annotated)

src/share/classes/com/sun/tools/javadoc/SerializedForm.java