Tue, 15 Jul 2008 19:22:51 -0700
6657907: javadoc has unchecked warnings
Reviewed-by: bpatel
1 /*
2 * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
26 package com.sun.tools.javadoc;
28 import com.sun.javadoc.*;
30 import com.sun.tools.javac.code.Flags;
31 import com.sun.tools.javac.code.Kinds;
32 import com.sun.tools.javac.code.Scope;
33 import com.sun.tools.javac.code.Symbol.VarSymbol;
34 import com.sun.tools.javac.code.Symbol.ClassSymbol;
35 import com.sun.tools.javac.code.Symbol.MethodSymbol;
36 import com.sun.tools.javac.util.Name;
37 import com.sun.tools.javac.util.ListBuffer;
39 /**
40 * The serialized form is the specification of a class' serialization
41 * state. <p>
42 *
43 * It consists of the following information:<p>
44 *
45 * <pre>
46 * 1. Whether class is Serializable or Externalizable.
47 * 2. Javadoc for serialization methods.
48 * a. For Serializable, the optional readObject, writeObject,
49 * readResolve and writeReplace.
50 * serialData tag describes, in prose, the sequence and type
51 * of optional data written by writeObject.
52 * b. For Externalizable, writeExternal and readExternal.
53 * serialData tag describes, in prose, the sequence and type
54 * of optional data written by writeExternal.
55 * 3. Javadoc for serialization data layout.
56 * a. For Serializable, the name,type and description
57 * of each Serializable fields.
58 * b. For Externalizable, data layout is described by 2(b).
59 * </pre>
60 *
61 * @since 1.2
62 * @author Joe Fialli
63 * @author Neal Gafter (rewrite but not too proud)
64 */
65 class SerializedForm {
66 ListBuffer<MethodDoc> methods = new ListBuffer<MethodDoc>();
68 /* List of FieldDocImpl - Serializable fields.
69 * Singleton list if class defines Serializable fields explicitly.
70 * Otherwise, list of default serializable fields.
71 * 0 length list for Externalizable.
72 */
73 private final ListBuffer<FieldDocImpl> fields = new ListBuffer<FieldDocImpl>();
75 /* True if class specifies serializable fields explicitly.
76 * using special static member, serialPersistentFields.
77 */
78 private boolean definesSerializableFields = false;
80 // Specially treated field/method names defined by Serialization.
81 private static final String SERIALIZABLE_FIELDS = "serialPersistentFields";
82 private static final String READOBJECT = "readObject";
83 private static final String WRITEOBJECT = "writeObject";
84 private static final String READRESOLVE = "readResolve";
85 private static final String WRITEREPLACE = "writeReplace";
86 private static final String READOBJECTNODATA = "readObjectNoData";
88 /**
89 * Constructor.
90 *
91 * Catalog Serializable fields for Serializable class.
92 * Catalog serialization methods for Serializable and
93 * Externalizable classes.
94 */
95 SerializedForm(DocEnv env, ClassSymbol def, ClassDocImpl cd) {
96 if (cd.isExternalizable()) {
97 /* look up required public accessible methods,
98 * writeExternal and readExternal.
99 */
100 String[] readExternalParamArr = { "java.io.ObjectInput" };
101 String[] writeExternalParamArr = { "java.io.ObjectOutput" };
102 MethodDoc md = cd.findMethod("readExternal", readExternalParamArr);
103 if (md != null) {
104 methods.append(md);
105 }
106 md = cd.findMethod("writeExternal", writeExternalParamArr);
107 if (md != null) {
108 methods.append(md);
109 Tag tag[] = md.tags("serialData");
110 }
111 // } else { // isSerializable() //### ???
112 } else if (cd.isSerializable()) {
114 VarSymbol dsf = getDefinedSerializableFields(def);
115 if (dsf != null) {
117 /* Define serializable fields with array of ObjectStreamField.
118 * Each ObjectStreamField should be documented by a
119 * serialField tag.
120 */
121 definesSerializableFields = true;
122 //### No modifier filtering applied here.
123 FieldDocImpl dsfDoc = env.getFieldDoc(dsf);
124 fields.append(dsfDoc);
125 mapSerialFieldTagImplsToFieldDocImpls(dsfDoc, env, def);
126 } else {
128 /* Calculate default Serializable fields as all
129 * non-transient, non-static fields.
130 * Fields should be documented by serial tag.
131 */
132 computeDefaultSerializableFields(env, def, cd);
133 }
135 /* Check for optional customized readObject, writeObject,
136 * readResolve and writeReplace, which can all contain
137 * the serialData tag. */
138 addMethodIfExist(env, def, READOBJECT);
139 addMethodIfExist(env, def, WRITEOBJECT);
140 addMethodIfExist(env, def, READRESOLVE);
141 addMethodIfExist(env, def, WRITEREPLACE);
142 addMethodIfExist(env, def, READOBJECTNODATA);
143 }
144 }
146 /*
147 * Check for explicit Serializable fields.
148 * Check for a private static array of ObjectStreamField with
149 * name SERIALIZABLE_FIELDS.
150 */
151 private VarSymbol getDefinedSerializableFields(ClassSymbol def) {
152 Name.Table names = def.name.table;
154 /* SERIALIZABLE_FIELDS can be private,
155 * so must lookup by ClassSymbol, not by ClassDocImpl.
156 */
157 for (Scope.Entry e = def.members().lookup(names.fromString(SERIALIZABLE_FIELDS)); e.scope != null; e = e.next()) {
158 if (e.sym.kind == Kinds.VAR) {
159 VarSymbol f = (VarSymbol)e.sym;
160 if ((f.flags() & Flags.STATIC) != 0 &&
161 (f.flags() & Flags.PRIVATE) != 0) {
162 return f;
163 }
164 }
165 }
166 return null;
167 }
169 /*
170 * Compute default Serializable fields from all members of ClassSymbol.
171 *
172 * Since the fields of ClassDocImpl might not contain private or
173 * package accessible fields, must walk over all members of ClassSymbol.
174 */
175 private void computeDefaultSerializableFields(DocEnv env,
176 ClassSymbol def,
177 ClassDocImpl cd) {
178 for (Scope.Entry e = def.members().elems; e != null; e = e.sibling) {
179 if (e.sym != null && e.sym.kind == Kinds.VAR) {
180 VarSymbol f = (VarSymbol)e.sym;
181 if ((f.flags() & Flags.STATIC) == 0 &&
182 (f.flags() & Flags.TRANSIENT) == 0) {
183 //### No modifier filtering applied here.
184 FieldDocImpl fd = env.getFieldDoc(f);
185 //### Add to beginning.
186 //### Preserve order used by old 'javadoc'.
187 fields.prepend(fd);
188 }
189 }
190 }
191 }
193 /*
194 * Catalog Serializable method if it exists in current ClassSymbol.
195 * Do not look for method in superclasses.
196 *
197 * Serialization requires these methods to be non-static.
198 *
199 * @param method should be an unqualified Serializable method
200 * name either READOBJECT, WRITEOBJECT, READRESOLVE
201 * or WRITEREPLACE.
202 * @param visibility the visibility flag for the given method.
203 */
204 private void addMethodIfExist(DocEnv env, ClassSymbol def, String methodName) {
205 Name.Table names = def.name.table;
207 for (Scope.Entry e = def.members().lookup(names.fromString(methodName)); e.scope != null; e = e.next()) {
208 if (e.sym.kind == Kinds.MTH) {
209 MethodSymbol md = (MethodSymbol)e.sym;
210 if ((md.flags() & Flags.STATIC) == 0) {
211 /*
212 * WARNING: not robust if unqualifiedMethodName is overloaded
213 * method. Signature checking could make more robust.
214 * READOBJECT takes a single parameter, java.io.ObjectInputStream.
215 * WRITEOBJECT takes a single parameter, java.io.ObjectOutputStream.
216 */
217 methods.append(env.getMethodDoc(md));
218 }
219 }
220 }
221 }
223 /*
224 * Associate serialField tag fieldName with FieldDocImpl member.
225 * Note: A serialField tag does not have to map an existing field
226 * of a class.
227 */
228 private void mapSerialFieldTagImplsToFieldDocImpls(FieldDocImpl spfDoc,
229 DocEnv env,
230 ClassSymbol def) {
231 Name.Table names = def.name.table;
233 SerialFieldTag[] sfTag = spfDoc.serialFieldTags();
234 for (int i = 0; i < sfTag.length; i++) {
235 Name fieldName = names.fromString(sfTag[i].fieldName());
237 // Look for a FieldDocImpl that is documented by serialFieldTagImpl.
238 for (Scope.Entry e = def.members().lookup(fieldName); e.scope != null; e = e.next()) {
239 if (e.sym.kind == Kinds.VAR) {
240 VarSymbol f = (VarSymbol)e.sym;
241 FieldDocImpl fdi = env.getFieldDoc(f);
242 ((SerialFieldTagImpl)(sfTag[i])).mapToFieldDocImpl(fdi);
243 break;
244 }
245 }
246 }
247 }
249 /**
250 * Return serializable fields in class. <p>
251 *
252 * Returns either a list of default fields documented by serial tag comment or
253 * javadoc comment<p>
254 * Or Returns a single FieldDocImpl for serialPersistentField. There is a
255 * serialField tag for each serializable field.<p>
256 *
257 * @return an array of FieldDocImpl for representing the visible
258 * fields in this class.
259 */
260 FieldDoc[] fields() {
261 return (FieldDoc[])fields.toArray(new FieldDocImpl[fields.length()]);
262 }
264 /**
265 * Return serialization methods in class.
266 *
267 * @return an array of MethodDocImpl for serialization methods in this class.
268 */
269 MethodDoc[] methods() {
270 return methods.toArray(new MethodDoc[methods.length()]);
271 }
273 /**
274 * Returns true if Serializable fields are defined explicitly using
275 * member, serialPersistentFields.
276 *
277 * @see #fields()
278 */
279 boolean definesSerializableFields() {
280 return definesSerializableFields;
281 }
282 }