harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [6/10] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
Date Fri, 01 May 2009 08:09:01 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutputStream.java Fri May  1 08:08:59 2009
@@ -28,9 +28,9 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * An ObjectOutputStream can be used to save Java objects into a stream where
- * the objects can be loaded later with an ObjectInputStream. Primitive data
- * (ints, bytes, chars, etc) can also be saved.
+ * A specialized {@link OutputStream} that is able to write (serialize) Java
+ * objects as well as primitive data types (int, byte, char etc.). The data can
+ * later be loaded using an ObjectInputStream.
  * 
  * @see ObjectInputStream
  * @see ObjectOutput
@@ -121,29 +121,117 @@
     private final ObjectStreamClass proxyClassDesc = ObjectStreamClass.lookup(Proxy.class); 
   
     /**
-     * Inner class to provide access to serializable fields
+     * PutField is an inner class to provide access to the persistent fields
+     * that are written to the target stream.
      */
     public static abstract class PutField {
+        /**
+         * Puts the value of the boolean field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, boolean value);
 
+        /**
+         * Puts the value of the character field identified by {@code name} to
+         * the persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, char value);
 
+        /**
+         * Puts the value of the byte field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, byte value);
 
+        /**
+         * Puts the value of the short field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, short value);
 
+        /**
+         * Puts the value of the integer field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, int value);
 
+        /**
+         * Puts the value of the long field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, long value);
 
+        /**
+         * Puts the value of the float field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, float value);
 
+        /**
+         * Puts the value of the double field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, double value);
 
+        /**
+         * Puts the value of the Object field identified by {@code name} to the
+         * persistent field.
+         *
+         * @param name
+         *            the name of the field to serialize.
+         * @param value
+         *            the value that is put to the persistent field.
+         */
         public abstract void put(String name, Object value);
 
         /**
-         * @deprecated This method is unsafe and may corrupt the output stream.
+         * Writes the fields to the target stream {@code out}.
+         *
+         * @param out
+         *            the target stream
+         * @throws IOException
+         *             if an error occurs while writing to the target stream.
+         * @deprecated This method is unsafe and may corrupt the target stream.
          *             Use ObjectOutputStream#writeFields() instead.
          */
         @Deprecated
@@ -151,13 +239,15 @@
     }
 
     /**
-     * Constructs a new <code>ObjectOutputStream</code>. The representation
-     * and proper initialization is in the hands of subclasses.
+     * Constructs a new {@code ObjectOutputStream}. This default constructor can
+     * be used by subclasses that do not want to use the public constructor if
+     * it allocates unneeded data.
      * 
      * @throws IOException
+     *             if an error occurs when creating this stream.
      * @throws SecurityException
-     *             if subclassing this is not allowed
-     * 
+     *             if a security manager is installed and it denies subclassing
+     *             this class.
      * @see SecurityManager#checkPermission(java.security.Permission)
      */
     protected ObjectOutputStream() throws IOException, SecurityException {
@@ -174,15 +264,18 @@
     }
 
     /**
-     * Constructs a new ObjectOutputStream on the OutputStream
-     * <code>output</code>. All writes are now filtered through this stream.
+     * Constructs a new ObjectOutputStream that writes to the OutputStream
+     * {@code output}.
      * 
      * @param output
-     *            The non-null OutputStream to filter writes on.
+     *            the non-null OutputStream to filter writes on.
      * 
      * @throws IOException
-     *             If an IO exception happened when writing the object stream
+     *             if an error occurs while writing the object stream
      *             header
+     * @throws SecurityException
+     *             if a security manager is installed and it denies subclassing
+     *             this class.
      */
     public ObjectOutputStream(OutputStream output) throws IOException {
         Class<?> implementationClass = getClass();
@@ -229,35 +322,31 @@
     }
 
     /**
-     * Writes optional information for class <code>aClass</code> into the
-     * stream represented by the receiver. This optional data can be read when
-     * deserializing the class descriptor (ObjectStreamClass) for this class
-     * from the input stream. By default no extra data is saved.
+     * Writes optional information for class {@code aClass} to the output
+     * stream. This optional data can be read when deserializing the class
+     * descriptor (ObjectStreamClass) for this class from an input stream. By
+     * default, no extra data is saved.
      * 
      * @param aClass
-     *            The class to annotate
-     * 
+     *            the class to annotate.
      * @throws IOException
-     *             If an IO exception happened when annotating the class.
-     * 
-     * @see ObjectInputStream#resolveClass
+     *             if an error occurs while writing to the target stream.
+     * @see ObjectInputStream#resolveClass(ObjectStreamClass)
      */
     protected void annotateClass(Class<?> aClass) throws IOException {
         // By default no extra info is saved. Subclasses can override
     }
 
     /**
-     * Writes optional information for a proxy class into the stream represented
-     * by the receiver. This optional data can be read when deserializing the
-     * proxy class from the input stream. By default no extra data is saved.
+     * Writes optional information for a proxy class to the target stream. This
+     * optional data can be read when deserializing the proxy class from an
+     * input stream. By default, no extra data is saved.
      * 
      * @param aClass
-     *            The proxy class to annotate
-     * 
+     *            the proxy class to annotate.
      * @throws IOException
-     *             If an IO exception happened when annotating the class.
-     * 
-     * @see ObjectInputStream#resolveProxyClass
+     *             if an error occurs while writing to the target stream.
+     * @see ObjectInputStream#resolveProxyClass(String[])
      */
     protected void annotateProxyClass(Class<?> aClass) throws IOException {
         // By default no extra info is saved. Subclasses can override
@@ -277,11 +366,11 @@
     }
 
     /**
-     * Close this ObjectOutputStream. Any buffered data is flushed. This
-     * implementation closes the target stream.
+     * Closes this stream. Any buffered data is flushed. This implementation
+     * closes the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this stream.
+     *             if an error occurs while closing this stream.
      */
     @Override
     public void close() throws IOException {
@@ -303,12 +392,14 @@
     }
 
     /**
-     * Default method to write objects into the receiver. Fields defined in the
-     * object's class and superclasses (which are Serializable) will be saved.
+     * Default method to write objects to this stream. Serializable fields
+     * defined in the object's class and superclasses are written to the output
+     * stream.
      * 
      * @throws IOException
-     *             If an IO error occurs attempting to write the object data
-     * 
+     *             if an error occurs while writing to the target stream.
+     * @throws NotActiveException
+     *             if this method is not called from {@code writeObject()}.
      * @see ObjectInputStream#defaultReadObject
      */
     public void defaultWriteObject() throws IOException {
@@ -320,10 +411,11 @@
     }
 
     /**
-     * Flushes buffered primitive data into the receiver.
+     * Writes buffered data to the target stream. This is similar to {@code
+     * flush} but the flush is not propagated to the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to drain the data
+     *             if an error occurs while writing to the target stream.
      */
     protected void drain() throws IOException {
         if (primitiveTypes == null || primitiveTypesBuffer == null) {
@@ -356,19 +448,19 @@
     }
 
     /**
-     * Dumps the parameter <code>obj</code> only if it is <code>null</code>
+     * Dumps the parameter {@code obj} only if it is {@code null}
      * or an object that has already been dumped previously.
      * 
      * @param obj
      *            Object to check if an instance previously dumped by this
      *            stream.
      * @return null if it is an instance which has not been dumped yet (and this
-     *         method does nothing). Integer, if <code>obj</code> is an
+     *         method does nothing). Integer, if {@code obj} is an
      *         instance which has been dumped already. In this case this method
      *         saves the cyclic reference.
      * 
      * @throws IOException
-     *             If an error occurs attempting to save <code>null</code> or
+     *             If an error occurs attempting to save {@code null} or
      *             a cyclic reference.
      */
     private Integer dumpCycle(Object obj) throws IOException {
@@ -382,18 +474,17 @@
     }
 
     /**
-     * Enables/disables object replacement for the receiver. By default this is
-     * not enabled. Only trusted subclasses (loaded with system class loader)
-     * can override this behavior.
+     * Enables object replacement for this stream. By default this is not
+     * enabled. Only trusted subclasses (loaded with system class loader) are
+     * allowed to change this status.
      * 
      * @param enable
-     *            if true, enables replacement. If false, disables replacement.
-     * @return boolean the previous configuration (if it was enabled or
-     *         disabled)
-     * 
+     *            {@code true} to enable object replacement; {@code false} to
+     *            disable it.
+     * @return the previous setting.
      * @throws SecurityException
-     *             If the class of the receiver is not trusted
-     * 
+     *             if a security manager is installed and it denies enabling
+     *             object replacement for this stream.
      * @see #replaceObject
      * @see ObjectInputStream#enableResolveObject
      */
@@ -413,12 +504,12 @@
     }
 
     /**
-     * Flush this ObjectOutputStream. Any pending writes to the underlying
-     * stream are written out when this method is invoked.
+     * Writes buffered data to the target stream and calls the {@code flush}
+     * method of the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this
-     *             ObjectOutputStream.
+     *             if an error occurs while writing to or flushing the output
+     *             stream.
      */
     @Override
     public void flush() throws IOException {
@@ -438,18 +529,17 @@
     }
 
     /**
-     * Return the <code>PutField</code> object for the receiver. This allows
-     * users to transfer values from actual object fields in the object being
-     * dumped to the emulated fields represented by the <code>PutField</code>
-     * returned by this method.
-     * 
-     * @return the PutFieldObject for the receiver
+     * Gets this stream's {@code PutField} object. This object provides access
+     * to the persistent fields that are eventually written to the output
+     * stream. It is used to transfer the values from the fields of the object
+     * that is currently being written to the persistent fields.
      * 
+     * @return the PutField object from which persistent fields can be accessed
+     *         by name.
      * @throws IOException
-     *             If an IO error occurs
+     *             if an I/O error occurs.
      * @throws NotActiveException
-     *             If this method is not called from writeObject()
-     * 
+     *             if this method is not called from {@code writeObject()}.
      * @see ObjectInputStream#defaultReadObject
      */
     public PutField putFields() throws IOException {
@@ -464,9 +554,9 @@
     }
 
     /**
-     * Assume object <code>obj</code> has not been dumped yet, and assign a
+     * Assume object {@code obj} has not been dumped yet, and assign a
      * handle to it
-     * 
+     *
      * @param obj
      *            Non-null object being dumped.
      * @return the handle that this object is being assigned.
@@ -497,17 +587,17 @@
     }
 
     /**
-     * If <code>enableReplaceObject()</code> was activated, computes the
-     * replacement object for the original object <code>object</code> and
-     * returns the replacement. Otherwise returns <code>object</code>.
-     * 
+     * Allows trusted subclasses to substitute the specified original {@code
+     * object} with a new object. Object substitution has to be activated first
+     * with calling {@code enableReplaceObject(true)}. This implementation just
+     * returns {@code object}.
+     *
      * @param object
-     *            Original object for which a replacement may be defined
-     * @return a possibly new, replacement object for <code>object</code>
-     * 
+     *            the original object for which a replacement may be defined.
+     * @return the replacement object for {@code object}.
      * @throws IOException
-     *             If any IO problem occurred when trying to resolve the object.
-     * 
+     *             if any I/O error occurs while creating the replacement
+     *             object.
      * @see #enableReplaceObject
      * @see ObjectInputStream#enableResolveObject
      * @see ObjectInputStream#resolveObject
@@ -518,13 +608,15 @@
     }
 
     /**
-     * Reset the receiver. A marker is written to the stream, so that
-     * deserialization will also perform a rest at the same point. Objects
-     * previously written are no longer remembered, so they will be written
-     * again (instead of a cyclical reference) if found in the object graph.
+     * Resets the state of this stream. A marker is written to the stream, so
+     * that the corresponding input stream will also perform a reset at the same
+     * point. Objects previously written are no longer remembered, so they will
+     * be written again (instead of a cyclical reference) if found in the object
+     * graph.
      * 
      * @throws IOException
-     *             If any IO problem occurred when trying to reset the receiver
+     *             if {@code reset()} is called during the serialization of an
+     *             object.
      */
     public void reset() throws IOException {
         // First we flush what we have
@@ -561,13 +653,18 @@
     }
 
     /**
-     * Set the receiver to use the given protocol version.
+     * Sets the specified protocol version to be used by this stream.
      * 
      * @param version
-     *            protocol version to be used
-     * 
-     * @throws IOException
-     *             If an IO error occurs
+     *            the protocol version to be used. Use a {@code
+     *            PROTOCOL_VERSION_x} constant from {@code
+     *            java.io.ObjectStreamConstants}.
+     * @throws IllegalArgumentException
+     *             if an invalid {@code version} is specified.
+     * @throws IOException
+     *             if an I/O error occurs.
+     * @see ObjectStreamConstants#PROTOCOL_VERSION_1
+     * @see ObjectStreamConstants#PROTOCOL_VERSION_2
      */
     public void useProtocolVersion(int version) throws IOException {
         if (!objectsWritten.isEmpty()) {
@@ -583,15 +680,13 @@
     }
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to
-     * this ObjectOutputStream.
+     * Writes the entire contents of the byte array {@code buffer} to the output
+     * stream. Blocks until all bytes are written.
      * 
      * @param buffer
-     *            the buffer to be written
-     * 
+     *            the buffer to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             ObjectOutputStream.
+     *             if an error occurs while writing to the target stream.
      */
     @Override
     public void write(byte[] buffer) throws IOException {
@@ -600,19 +695,19 @@
     }
 
     /**
-     * Writes <code>length</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at offset <code>offset</code> to the
-     * ObjectOutputStream.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * offset {@code index} to the target stream. Blocks until all bytes are
+     * written.
      * 
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to write.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the index of the first byte in {@code buffer} to write.
      * @param length
-     *            number of bytes in buffer to write
-     * 
+     *            the number of bytes from {@code buffer} to write to the output
+     *            stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this OutputStream.
+     *             if an error occurs while writing to the target stream.
      */
     @Override
     public void write(byte[] buffer, int offset, int length) throws IOException {
@@ -621,14 +716,14 @@
     }
 
     /**
-     * Write one byte (<code>value</code>) into the receiver's underlying
-     * stream.
+     * Writes a single byte to the target stream. Only the least significant
+     * byte of the integer {@code value} is written to the stream. Blocks until
+     * the byte is actually written.
      * 
      * @param value
-     *            The primitive data to write. Only the lower byte is written.
-     * 
+     *            the byte to write.
      * @throws IOException
-     *             If an IO exception happened when writing the byte.
+     *             if an error occurs while writing to the target stream.
      */
     @Override
     public void write(int value) throws IOException {
@@ -637,14 +732,12 @@
     }
 
     /**
-     * Write primitive data of type boolean (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a boolean to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the boolean value to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeBoolean(boolean value) throws IOException {
         checkWritePrimitiveTypes();
@@ -652,14 +745,12 @@
     }
 
     /**
-     * Write primitive data of type byte (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a byte (8 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the byte to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeByte(int value) throws IOException {
         checkWritePrimitiveTypes();
@@ -667,15 +758,14 @@
     }
 
     /**
-     * Write a String as a sequence of bytes (only lower-order 8 bits of each
-     * char are written), as primitive data (<code>value</code>) into the
-     * receiver's underlying stream.
+     * Writes the string {@code value} as a sequence of bytes to the target
+     * stream. Only the least significant byte of each character in the string
+     * is written.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the string to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeBytes(String value) throws IOException {
         checkWritePrimitiveTypes();
@@ -683,14 +773,12 @@
     }
 
     /**
-     * Write primitive data of type char (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a character (16 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the character to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeChar(int value) throws IOException {
         checkWritePrimitiveTypes();
@@ -698,14 +786,13 @@
     }
 
     /**
-     * Write a String as a sequence of char, as primitive data (<code>value</code>)
-     * into the receiver's underlying stream.
+     * Writes the string {@code value} as a sequence of characters to the target
+     * stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the string to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeChars(String value) throws IOException {
         checkWritePrimitiveTypes();
@@ -713,11 +800,11 @@
     }
 
     /**
-     * Write a class descriptor <code>classDesc</code> (an
-     * <code>ObjectStreamClass</code>) to the stream.
+     * Write a class descriptor {@code classDesc} (an
+     * {@code ObjectStreamClass}) to the stream.
      * 
      * @param classDesc
-     *            The class descriptor (an <code>ObjectStreamClass</code>) to
+     *            The class descriptor (an {@code ObjectStreamClass}) to
      *            be dumped
      * @param unshared
      *            Write the object unshared
@@ -805,14 +892,12 @@
     }
 
     /**
-     * Write primitive data of type double (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a double (64 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the double to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeDouble(double value) throws IOException {
         checkWritePrimitiveTypes();
@@ -821,11 +906,11 @@
 
     /**
      * Writes a collection of field descriptors (name, type name, etc) for the
-     * class descriptor <code>classDesc</code> (an
-     * <code>ObjectStreamClass</code>)
+     * class descriptor {@code classDesc} (an
+     * {@code ObjectStreamClass})
      * 
      * @param classDesc
-     *            The class descriptor (an <code>ObjectStreamClass</code>)
+     *            The class descriptor (an {@code ObjectStreamClass})
      *            for which to write field information
      * @param externalizable
      *            true if the descriptors are externalizable
@@ -863,14 +948,14 @@
     }
 
     /**
-     * Write the fields of the object being dumped. The stream will use the
-     * currently active <code>PutField</code> object, allowing users to dump
-     * emulated fields, for cross-loading compatibility when a class definition
-     * changes.
+     * Writes the fields of the object currently being written to the target
+     * stream. The field values are buffered in the currently active {@code
+     * PutField} object, which can be accessed by calling {@code putFields()}.
      * 
      * @throws IOException
-     *             If an IO error occurs
-     * 
+     *             if an error occurs while writing to the target stream.
+     * @throws NotActiveException
+     *             if there are no fields to write to the target stream.
      * @see #putFields
      */
     public void writeFields() throws IOException {
@@ -883,11 +968,11 @@
 
     /**
      * Writes a collection of field values for the emulated fields
-     * <code>emulatedFields</code>
+     * {@code emulatedFields}
      * 
      * @param emulatedFields
-     *            an <code>EmulatedFieldsForDumping</code>, concrete subclass
-     *            of <code>PutField</code>
+     *            an {@code EmulatedFieldsForDumping}, concrete subclass
+     *            of {@code PutField}
      * 
      * @throws IOException
      *             If an IO exception happened when writing the field values.
@@ -940,15 +1025,15 @@
 
     /**
      * Writes a collection of field values for the fields described by class
-     * descriptor <code>classDesc</code> (an <code>ObjectStreamClass</code>).
+     * descriptor {@code classDesc} (an {@code ObjectStreamClass}).
      * This is the default mechanism, when emulated fields (an
-     * <code>PutField</code>) are not used. Actual values to dump are fetched
-     * directly from object <code>obj</code>.
+     * {@code PutField}) are not used. Actual values to dump are fetched
+     * directly from object {@code obj}.
      * 
      * @param obj
      *            Instance from which to fetch field values to dump.
      * @param classDesc
-     *            A class descriptor (an <code>ObjectStreamClass</code>)
+     *            A class descriptor (an {@code ObjectStreamClass})
      *            defining which fields should be dumped.
      * 
      * @throws IOException
@@ -1018,14 +1103,12 @@
     }
 
     /**
-     * Write primitive data of type float (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a float (32 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the float to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeFloat(float value) throws IOException {
         checkWritePrimitiveTypes();
@@ -1034,17 +1117,17 @@
 
     /**
      * Walks the hierarchy of classes described by class descriptor
-     * <code>classDesc</code> and writes the field values corresponding to
+     * {@code classDesc} and writes the field values corresponding to
      * fields declared by the corresponding class descriptor. The instance to
-     * fetch field values from is <code>object</code>. If the class
-     * (corresponding to class descriptor <code>classDesc</code>) defines
-     * private instance method <code>writeObject</code> it will be used to
+     * fetch field values from is {@code object}. If the class
+     * (corresponding to class descriptor {@code classDesc}) defines
+     * private instance method {@code writeObject} it will be used to
      * dump field values.
      * 
      * @param object
      *            Instance from which to fetch field values to dump.
      * @param classDesc
-     *            A class descriptor (an <code>ObjectStreamClass</code>)
+     *            A class descriptor (an {@code ObjectStreamClass})
      *            defining which fields should be dumped.
      * 
      * @throws IOException
@@ -1115,14 +1198,12 @@
     }
 
     /**
-     * Write primitive data of type int (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes an integer (32 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the integer to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeInt(int value) throws IOException {
         checkWritePrimitiveTypes();
@@ -1130,14 +1211,12 @@
     }
 
     /**
-     * Write primitive data of type long (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a long (64 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the long to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeLong(long value) throws IOException {
         checkWritePrimitiveTypes();
@@ -1145,18 +1224,18 @@
     }
 
     /**
-     * Write array <code>array</code> of class <code>arrayClass</code> with
-     * component type <code>componentType</code> into the receiver. It is
-     * assumed the array has not been dumped yet. Return an <code>Integer</code>
+     * Write array {@code array} of class {@code arrayClass} with
+     * component type {@code componentType} into the receiver. It is
+     * assumed the array has not been dumped yet. Return an {@code Integer}
      * that represents the handle for this object (array) which is dumped here.
      * 
      * @param array
      *            The array object to dump
      * @param arrayClass
-     *            A <code>java.lang.Class</code> representing the class of the
+     *            A {@code java.lang.Class} representing the class of the
      *            array
      * @param componentType
-     *            A <code>java.lang.Class</code> representing the array
+     *            A {@code java.lang.Class} representing the array
      *            component type
      * @return the handle assigned to the array
      * 
@@ -1247,14 +1326,14 @@
     }
 
     /**
-     * Write class <code>object</code> into the receiver. It is assumed the
+     * Write class {@code object} into the receiver. It is assumed the
      * class has not been dumped yet. Classes are not really dumped, but a class
-     * descriptor (<code>ObjectStreamClass</code>) that corresponds to them.
-     * Return an <code>Integer</code> that represents the handle for this
+     * descriptor ({@code ObjectStreamClass}) that corresponds to them.
+     * Return an {@code Integer} that represents the handle for this
      * object (class) which is dumped here.
      * 
      * @param object
-     *            The <code>java.lang.Class</code> object to dump
+     *            The {@code java.lang.Class} object to dump
      * @return the handle assigned to the class being dumped
      * 
      * @throws IOException
@@ -1289,14 +1368,14 @@
     }
 
     /**
-     * Write class descriptor <code>classDesc</code> into the receiver. It is
+     * Write class descriptor {@code classDesc} into the receiver. It is
      * assumed the class descriptor has not been dumped yet. The class
      * descriptors for the superclass chain will be dumped as well. Return an
-     * <code>Integer</code> that represents the handle for this object (class
+     * {@code Integer} that represents the handle for this object (class
      * descriptor) which is dumped here.
      * 
      * @param classDesc
-     *            The <code>ObjectStreamClass</code> object to dump
+     *            The {@code ObjectStreamClass} object to dump
      * 
      * @throws IOException
      *             If an IO exception happened when writing the class
@@ -1329,14 +1408,12 @@
     }
 
     /**
-     * Write class descriptor <code>classDesc</code> into the receiver.
+     * Writes a class descriptor to the target stream.
      * 
      * @param classDesc
-     *            The <code>ObjectStreamClass</code> object to dump
-     * 
+     *            the class descriptor to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the class
-     *             descriptor.
+     *             if an error occurs while writing to the target stream.
      */
     protected void writeClassDescriptor(ObjectStreamClass classDesc)
             throws IOException {
@@ -1344,8 +1421,8 @@
     }
 
     /**
-     * Write exception <code>ex</code> into the receiver. It is assumed the
-     * exception has not been dumped yet. Return an <code>Integer</code> that
+     * Write exception {@code ex} into the receiver. It is assumed the
+     * exception has not been dumped yet. Return an {@code Integer} that
      * represents the handle for this object (exception) which is dumped here.
      * This is used to dump the exception instance that happened (if any) when
      * dumping the original object graph. The set of seen objects will be reset
@@ -1370,21 +1447,21 @@
     }
 
     /**
-     * Write object <code>object</code> of class <code>theClass</code> into
+     * Write object {@code object} of class {@code theClass} into
      * the receiver. It is assumed the object has not been dumped yet. Return an
-     * <code>Integer</code> that represents the handle for this object which
+     * {@code Integer} that represents the handle for this object which
      * is dumped here.
      * 
-     * If the object implements <code>Externalizable</code> its
-     * <code>writeExternal</code> is called. Otherwise, all fields described
+     * If the object implements {@code Externalizable} its
+     * {@code writeExternal} is called. Otherwise, all fields described
      * by the class hierarchy is dumped. Each class can define how its declared
      * instance fields are dumped by defining a private method
-     * <code>writeObject</code>
+     * {@code writeObject}
      * 
      * @param object
      *            The object to dump
      * @param theClass
-     *            A <code>java.lang.Class</code> representing the class of the
+     *            A {@code java.lang.Class} representing the class of the
      *            object
      * @param unshared
      *            Write the object unshared
@@ -1463,13 +1540,13 @@
     }
     
     /**
-     * Write String <code>object</code> into the receiver. It is assumed the
-     * String has not been dumped yet. Return an <code>Integer</code> that
+     * Write String {@code object} into the receiver. It is assumed the
+     * String has not been dumped yet. Return an {@code Integer} that
      * represents the handle for this object (String) which is dumped here.
-     * Strings are saved in UTF format.
+     * Strings are saved encoded with {@link DataInput modified UTF-8}.
      * 
      * @param object
-     *            The <code>java.lang.String</code> object to dump
+     *            the string to dump.
      * @return the handle assigned to the String being dumped
      * 
      * @throws IOException
@@ -1497,26 +1574,24 @@
     }
 
     /**
-     * Write a special tag that indicates the value <code>null</code> into the
+     * Write a special tag that indicates the value {@code null} into the
      * receiver.
      * 
      * @throws IOException
      *             If an IO exception happened when writing the tag for
-     *             <code>null</code>.
+     *             {@code null}.
      */
     private void writeNull() throws IOException {
         output.writeByte(TC_NULL);
     }
 
     /**
-     * Write object <code>object</code> into the receiver's underlying stream.
+     * Writes an object to the target stream.
      * 
      * @param object
-     *            The object to write
-     * 
+     *            the object to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the object
-     * 
+     *             if an error occurs while writing to the target stream.
      * @see ObjectInputStream#readObject()
      */
     public final void writeObject(Object object) throws IOException {
@@ -1524,16 +1599,16 @@
     }
 
     /**
-     * Write object <code>object</code> into the receiver's underlying stream
-     * unshared with previously written identical objects.
+     * Writes an unshared object to the target stream. This method is identical
+     * to {@code writeObject}, except that it always writes a new object to the
+     * stream versus the use of back-referencing for identical objects by
+     * {@code writeObject}.
      * 
      * @param object
-     *            The object to write
-     * 
+     *            the object to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the object
-     * 
-     * @see ObjectInputStream#readObject()
+     *             if an error occurs while writing to the target stream.
+     * @see ObjectInputStream#readUnshared()
      */
     public void writeUnshared(Object object) throws IOException {
         writeObject(object, true);
@@ -1577,7 +1652,7 @@
     }
 
     /**
-     * Write object <code>object</code> into the receiver's underlying stream.
+     * Write object {@code object} into the receiver's underlying stream.
      * 
      * @param object
      *            The object to write
@@ -1819,14 +1894,13 @@
     }
 
     /**
-     * Method to be overridden by subclasses to write <code>object</code> into
-     * the receiver's underlying stream.
+     * Method to be overridden by subclasses to write {@code object} to the
+     * target stream.
      * 
      * @param object
-     *            the object
-     * 
+     *            the object to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the object
+     *             if an error occurs while writing to the target stream.
      */
     protected void writeObjectOverride(Object object) throws IOException {
         if (!subclassOverridingImplementation) {
@@ -1836,14 +1910,12 @@
     }
 
     /**
-     * Write primitive data of type short (<code>value</code>)into the
-     * receiver's underlying stream.
+     * Writes a short (16 bit) to the target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the short to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeShort(int value) throws IOException {
         checkWritePrimitiveTypes();
@@ -1851,10 +1923,10 @@
     }
 
     /**
-     * Writes the ObjectOutputStream header into the underlying stream.
+     * Writes the {@link ObjectOutputStream} header to the target stream.
      * 
      * @throws IOException
-     *             If an IO exception happened when writing the stream header.
+     *             if an error occurs while writing to the target stream.
      */
     protected void writeStreamHeader() throws IOException {
         output.writeShort(STREAM_MAGIC);
@@ -1862,14 +1934,13 @@
     }
 
     /**
-     * Write primitive data of type String (<code>value</code>) in UTF
-     * format into the receiver's underlying stream.
+     * Writes a string encoded with {@link DataInput modified UTF-8} to the
+     * target stream.
      * 
      * @param value
-     *            The primitive data to write
-     * 
+     *            the string to write to the target stream.
      * @throws IOException
-     *             If an IO exception happened when writing the primitive data.
+     *             if an error occurs while writing to the target stream.
      */
     public void writeUTF(String value) throws IOException {
         checkWritePrimitiveTypes();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamClass.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamClass.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamClass.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamClass.java Fri May  1 08:08:59 2009
@@ -37,13 +37,10 @@
 import org.apache.harmony.luni.util.ThreadLocalCache;
 
 /**
- * Instances of ObjectStreamClass are used to describe classes of objects used
- * by serialization. When objects are saved, information about all its
- * superclasses is also saved by the use of descriptors, instances of
- * ObjectStreamClass.
- * 
- * These descriptors carry information about the class they represent, such as -
- * The name of the class - SUID of the class - Field names and types
+ * Represents a descriptor for identifying a class during serialization and
+ * deserialization. Information contained in the descriptor includes the name
+ * and SUID of the class as well as field names and types. Information inherited
+ * from the superclasses is also taken into account.
  * 
  * @see ObjectOutputStream
  * @see ObjectInputStream
@@ -102,7 +99,7 @@
     }
 
     /**
-     * A value that indicates the class has no Serializable fields
+     * Constant indicating that the class has no Serializable fields.
      */
     public static final ObjectStreamField[] NO_FIELDS = new ObjectStreamField[0];
 
@@ -224,11 +221,11 @@
     }
 
     /**
-     * Compute class descriptor for a given class <code>cl</code>. 
+     * Compute class descriptor for a given class <code>cl</code>.
      * 
      * @param cl
      *            a java.langClass for which to compute the corresponding
-     *            descriptor 
+     *            descriptor
      * @return the computer class descriptor
      */
     private static ObjectStreamClass createClassDesc(Class<?> cl) {
@@ -388,7 +385,7 @@
     }
 
     /**
-     * Compute and return the Serial Version UID of the class <code>cl</code>.
+     * Compute and return the Serial Version UID of the class {@code cl}.
      * The value is computed based on the class name, superclass chain, field
      * names, method names, modifiers, etc.
      * 
@@ -603,8 +600,8 @@
     }
 
     /**
-     * Return what the serializaton specification calls "descriptor" given a
-     * field signature. signature.
+     * Returns what the serializaton specification calls "descriptor" given a
+     * field signature.
      * 
      * @param signature
      *            a field signature
@@ -627,13 +624,13 @@
     }
 
     /**
-     * Return the java.lang.reflect.Field <code>serialPersistentFields</code>
-     * if class <code>cl</code> implements it. Return null otherwise.
+     * Return the java.lang.reflect.Field {@code serialPersistentFields}
+     * if class {@code cl} implements it. Return null otherwise.
      * 
      * @param cl
      *            a java.lang.Class which to test
-     * @return <code>java.lang.reflect.Field</code> if the class has
-     *         serialPersistentFields <code>null</code> if the class does not
+     * @return {@code java.lang.reflect.Field} if the class has
+     *         serialPersistentFields {@code null} if the class does not
      *         have serialPersistentFields
      */
     static Field fieldSerialPersistentFields(Class<?> cl) {
@@ -653,11 +650,10 @@
     }
 
     /**
-     * Return the class (java.lang.Class) that the receiver represents
+     * Returns the class (java.lang.Class) for this descriptor.
      * 
-     * @return <code>null</code> if there is no corresponding class for the
-     *         receiver <code>Class</code> The loaded class corresponding to
-     *         the receiver
+     * @return the class in the local VM that this descriptor represents;
+     *         {@code null} if there is no corresponding class.
      */
     public Class<?> forClass() {
         if (resolvedClass != null) {
@@ -667,23 +663,23 @@
     }
 
     /**
-     * Return a String representing the signature for a Constructor
-     * <code>c</code>.
+     * Return a String representing the signature for a Constructor {@code c}.
      * 
      * @param c
      *            a java.lang.reflect.Constructor for which to compute the
      *            signature
      * @return the constructor's signature
-     * 
      */
     static native String getConstructorSignature(Constructor<?> c);
 
     /**
-     * Answers a given field by name.
+     * Gets a field descriptor of the class represented by this class
+     * descriptor.
      * 
      * @param name
-     *            name of the desired field.
-     * @return a given field by name.
+     *            the name of the desired field.
+     * @return the field identified by {@code name} or {@code null} if there is
+     *         no such field.
      */
     public ObjectStreamField getField(String name) {
         ObjectStreamField[] allFields = getFields();
@@ -697,7 +693,7 @@
     }
 
     /**
-     * Answers the collection of field descriptors for the fields of the
+     * Returns the collection of field descriptors for the fields of the
      * corresponding class
      * 
      * @return the receiver's collection of declared fields for the class it
@@ -717,11 +713,11 @@
     }
 
     /**
-     * Answers the collection of field descriptors for the fields of the
-     * corresponding class
+     * Returns a collection of field descriptors for the serialized fields of
+     * the class represented by this class descriptor.
      * 
-     * @return the receiver's collection of declared fields for the class it
-     *         represents
+     * @return an array of field descriptors or an array of length zero if there
+     *         are no fields in this descriptor's class.
      */
     public ObjectStreamField[] getFields() {
         copyFieldAttributes();
@@ -733,7 +729,7 @@
      * this.loadFields cannot get the "unshared" information when deserializing
      * fields using current implementation of ObjectInputStream. This method
      * provides a way to copy the "unshared" attribute from this.fields.
-     * 
+     *
      */
     private void copyFieldAttributes() {
         if ((loadFields == null) || fields == null) {
@@ -755,7 +751,7 @@
     }
 
     /**
-     * Answers the collection of field descriptors for the input fields of the
+     * Returns the collection of field descriptors for the input fields of the
      * corresponding class
      * 
      * @return the receiver's collection of input fields for the class it
@@ -766,7 +762,7 @@
     }
 
     /**
-     * Return a String representing the signature for a field <code>f</code>.
+     * Return a String representing the signature for a field {@code f}.
      * 
      * @param f
      *            a java.lang.reflect.Field for which to compute the signature
@@ -775,7 +771,7 @@
     private static native String getFieldSignature(Field f);
 
     /**
-     * Answers the flags for this descriptor, where possible combined values are
+     * Returns the flags for this descriptor, where possible combined values are
      * 
      * ObjectStreamConstants.SC_WRITE_METHOD
      * ObjectStreamConstants.SC_SERIALIZABLE
@@ -788,7 +784,7 @@
     }
 
     /**
-     * Return a String representing the signature for a method <code>m</code>.
+     * Return a String representing the signature for a method {@code m}.
      * 
      * @param m
      *            a java.lang.reflect.Method for which to compute the signature
@@ -797,26 +793,26 @@
     static native String getMethodSignature(Method m);
 
     /**
-     * Answers the name of the class represented by the receiver
+     * Returns the name of the class represented by this descriptor.
      * 
-     * @return fully qualified name of the class the receiver represents
+     * @return the fully qualified name of the class this descriptor represents.
      */
     public String getName() {
         return className;
     }
 
     /**
-     * Answers the Serial Version User ID of the class represented by the
-     * receiver
+     * Returns the Serial Version User ID of the class represented by this
+     * descriptor.
      * 
-     * @return SUID for the class represented by the receiver
+     * @return the SUID for the class represented by this descriptor.
      */
     public long getSerialVersionUID() {
         return svUID;
     }
 
     /**
-     * Answers the descriptor (ObjectStreamClass) of the superclass of the class
+     * Returns the descriptor (ObjectStreamClass) of the superclass of the class
      * represented by the receiver.
      * 
      * @return an ObjectStreamClass representing the superclass of the class
@@ -827,27 +823,27 @@
     }
 
     /**
-     * Return true if the given class <code>cl</code> has the
-     * compiler-generated method <code>clinit</code>. Even though it is
+     * Return true if the given class {@code cl} has the
+     * compiler-generated method {@code clinit}. Even though it is
      * compiler-generated, it is used by the serialization code to compute SUID.
      * This is unfortunate, since it may depend on compiler optimizations in
      * some cases.
      * 
      * @param cl
      *            a java.lang.Class which to test
-     * @return <code>true</code> if the class has <clinit> <code>false</code>
+     * @return {@code true} if the class has <clinit> {@code false}
      *         if the class does not have <clinit>
      */
     private static native boolean hasClinit(Class<?> cl);
 
     /**
-     * Return true if instances of class <code>cl</code> are Externalizable,
+     * Return true if instances of class {@code cl} are Externalizable,
      * false otherwise.
      * 
      * @param cl
      *            a java.lang.Class which to test
-     * @return <code>true</code> if instances of the class are Externalizable
-     *         <code>false</code> if instances of the class are not
+     * @return {@code true} if instances of the class are Externalizable
+     *         {@code false} if instances of the class are not
      *         Externalizable
      * 
      * @see Object#hashCode
@@ -861,23 +857,23 @@
      * <code>typecode<code> describes a primitive type
      *
      * @param typecode a char describing the typecode
-     * @return <code>true</code> if the typecode represents a primitive type 
-     * <code>false</code> if the typecode represents an Object type (including arrays)
+     * @return {@code true} if the typecode represents a primitive type
+     * {@code false} if the typecode represents an Object type (including arrays)
      *
-     * @see	Object#hashCode
+     * @see Object#hashCode
      */
     static boolean isPrimitiveType(char typecode) {
         return !(typecode == '[' || typecode == 'L');
     }
 
     /**
-     * Return true if instances of class <code>cl</code> are Serializable,
+     * Return true if instances of class {@code cl} are Serializable,
      * false otherwise.
      * 
      * @param cl
      *            a java.lang.Class which to test
-     * @return <code>true</code> if instances of the class are Serializable
-     *         <code>false</code> if instances of the class are not
+     * @return {@code true} if instances of the class are Serializable
+     *         {@code false} if instances of the class are not
      *         Serializable
      * 
      * @see Object#hashCode
@@ -961,17 +957,15 @@
     }
 
     /**
-     * Return the descriptor (ObjectStreamClass) corresponding to the class
-     * <code>cl</code>. If the class is not Serializable or Externalizable,
-     * null is returned.
+     * Returns the descriptor corresponding to the class {@code cl}. If the
+     * class is not serializable or externalizable then {@code null} is
+     * returned.
      * 
      * @param cl
      *            a java.langClass for which to obtain the corresponding
      *            descriptor
-     * @return <code>null</code> if instances of the class <code>cl</code>
-     *         are not Serializable or Externalizable
-     *         <code>ObjectStreamClass</code> The corresponding descriptor if
-     *         the class <code>cl</code> is Serializable or Externalizable
+     * @return the corresponding descriptor if the {@code cl} is serializable or
+     *         externalizable; {@code null} otherwise.
      */
     public static ObjectStreamClass lookup(Class<?> cl) {
         ObjectStreamClass osc = lookupStreamClass(cl);
@@ -985,14 +979,12 @@
 
     /**
      * Return the descriptor (ObjectStreamClass) corresponding to the class
-     * <code>cl</code>. Returns an ObjectStreamClass even if instances of the
+     * {@code cl}. Returns an ObjectStreamClass even if instances of the
      * class cannot be serialized
-     * 
+     *
      * @param cl
-     *            a <code>java.langClass</code> for which to obtain the
-     *            corresponding descriptor
-     * @param computeSUID
-     *            a boolean indicating if SUID should be computed or not.
+     *            a java.langClass for which to obtain the corresponding
+     *            descriptor
      * @return the corresponding descriptor
      */
     static ObjectStreamClass lookupStreamClass(Class<?> cl) {
@@ -1207,10 +1199,10 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
+     * Returns a string containing a concise, human-readable description of this
+     * descriptor.
      * 
-     * @return a printable representation for the receiver.
+     * @return a printable representation of this descriptor.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamConstants.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamConstants.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamConstants.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamConstants.java Fri May  1 08:08:59 2009
@@ -18,85 +18,168 @@
 package java.io;
 
 /**
- * Helper interface with constants used by the serialization implementation.
+ * A helper interface with constants used by the serialization implementation.
  */
 public abstract interface ObjectStreamConstants {
 
     /**
-     * Used for the stream header
+     * The stream header's magic number.
      */
     public static final short STREAM_MAGIC = (short) 0xaced;
 
     /**
-     * Used for the stream header
+     * The stream header's version number.
      */
     public static final short STREAM_VERSION = 5;
 
     // These are tags to indicate the stream contents
+
+    /**
+     * The minimum tag value.
+     */
     public static final byte TC_BASE = 0x70;
 
+    /**
+     * Tag to mark a {@code null} object reference.
+     */
     public static final byte TC_NULL = (byte) 0x70;
 
+    /**
+     * Tag to mark a reference to an object that has already been written to the
+     * stream.
+     */
     public static final byte TC_REFERENCE = (byte) 0x71;
 
+    /**
+     * Tag to mark a new class descriptor.
+     */
     public static final byte TC_CLASSDESC = (byte) 0x72;
 
+    /**
+     * Tag to mark a new object.
+     */
     public static final byte TC_OBJECT = (byte) 0x73;
 
+    /**
+     * Tag to mark a new string.
+     */
     public static final byte TC_STRING = (byte) 0x74;
 
+    /**
+     * Tag to mark a new array.
+     */
     public static final byte TC_ARRAY = (byte) 0x75;
 
+    /**
+     * Tag to mark a reference to a class.
+     */
     public static final byte TC_CLASS = (byte) 0x76;
 
+    /**
+     * Tag to mark a block of optional data. The byte following this tag
+     * indicates the size of the block.
+     */
     public static final byte TC_BLOCKDATA = (byte) 0x77;
 
+    /**
+     * Tag to mark the end of block data blocks for an object.
+     */
     public static final byte TC_ENDBLOCKDATA = (byte) 0x78;
 
+    /**
+     * Tag to mark a stream reset.
+     */
     public static final byte TC_RESET = (byte) 0x79;
 
+    /**
+     * Tag to mark a long block of data. The long following this tag
+     * indicates the size of the block.
+     */
     public static final byte TC_BLOCKDATALONG = (byte) 0x7A;
 
+    /**
+     * Tag to mark an exception.
+     */
     public static final byte TC_EXCEPTION = (byte) 0x7B;
 
+    /**
+     * Tag to mark a long string.
+     */
     public static final byte TC_LONGSTRING = (byte) 0x7C;
 
+    /**
+     * Tag to mark a new proxy class descriptor.
+     */
     public static final byte TC_PROXYCLASSDESC = (byte) 0x7D;
 
+    /**
+     * The maximum tag value.
+     */
     public static final byte TC_MAX = 0x7E;
 
     /**
-     * The first object dumped gets assigned this handle/ID
+     * Handle for the first object that gets serialized.
      */
     public static final int baseWireHandle = 0x007e0000;
 
+    /**
+     * Stream protocol version 1.
+     */
     public static final int PROTOCOL_VERSION_1 = 1;
 
+    /**
+     * Stream protocol version 2.
+     */
     public static final int PROTOCOL_VERSION_2 = 2;
 
+    /**
+     * Permission constant to enable subclassing of ObjectInputStream and
+     * ObjectOutputStream.
+     */
     public static final SerializablePermission SUBCLASS_IMPLEMENTATION_PERMISSION = new SerializablePermission(
             "enableSubclassImplementation"); //$NON-NLS-1$
 
+    /**
+     * Permission constant to enable object substitution during serialization
+     * and deserialization.
+     */
     public static final SerializablePermission SUBSTITUTION_PERMISSION = new SerializablePermission(
             "enableSubstitution"); //$NON-NLS-1$
 
     // Flags that indicate if the object was serializable, externalizable
     // and had a writeObject method when dumped.
+    /**
+     * Bit mask for the {@code flag} field in ObjectStreamClass. Indicates
+     * that a serializable class has its own {@code writeObject} method.
+     */
     public static final byte SC_WRITE_METHOD = 0x01; // If SC_SERIALIZABLE
 
+    /**
+     * Bit mask for the {@code flag} field in ObjectStreamClass. Indicates
+     * that a class is serializable.
+     */
     public static final byte SC_SERIALIZABLE = 0x02;
 
+    /**
+     * Bit mask for the {@code flag} field in ObjectStreamClass. Indicates
+     * that a class is externalizable.
+     */
     public static final byte SC_EXTERNALIZABLE = 0x04;
 
+    /**
+     * Bit mask for the {@code flag} field in ObjectStreamClass. Indicates
+     * that an externalizable class is written in block data mode.
+     */
     public static final byte SC_BLOCK_DATA = 0x08; // If SC_EXTERNALIZABLE
 
     /**
-     * constant for new enum
+     * Tag to mark a new enum.
      */
     public static final byte TC_ENUM = 0x7E;
 
     /**
-     * the bitmask denoting that the object is a enum
+     * Bit mask for the {@code flag} field in ObjectStreamClass. Indicates
+     * that a class is an enum type.
      */
     public static final byte SC_ENUM = 0x10;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamException.java Fri May  1 08:08:59 2009
@@ -18,9 +18,9 @@
 package java.io;
 
 /**
- * This is the superclass of all exceptions that can happen when serializing or
- * deserialing objects. The state of the stream is unknown when one of these
- * serialization-related exceptions are thrown.
+ * Signals some sort of problem during either serialization or deserialization
+ * of objects. This is actually the superclass of several other, more specific
+ * exception classes.
  * 
  * @see InvalidObjectException
  * @see NotActiveException
@@ -34,18 +34,19 @@
     private static final long serialVersionUID = 7260898174833392607L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code ObjectStreamException} with its stack trace
+     * filled in.
      */
     protected ObjectStreamException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code ObjectStreamException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     protected ObjectStreamException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamField.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamField.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamField.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamField.java Fri May  1 08:08:59 2009
@@ -24,9 +24,9 @@
 import org.apache.harmony.misc.accessors.ObjectAccessor;
 
 /**
- * This class represents object fields that are saved to the stream, by
- * serialization. Classes can define the collection of fields to be dumped,
- * which can differ from the actual object's declared fields.
+ * Describes a field for the purpose of serialization. Classes can define the
+ * collection of fields that are serialized, which may be different from the set
+ * of all declared fields.
  * 
  * @see ObjectOutputStream#writeFields()
  * @see ObjectInputStream#readFields()
@@ -68,12 +68,14 @@
     }
 
     /**
-     * Constructs an ObjectStreamField with the given name and the given type
+     * Constructs an ObjectStreamField with the specified name and type.
      * 
      * @param name
-     *            a String, the name of the field
+     *            the name of the field.
      * @param cl
-     *            A Class object representing the type of the field
+     *            the type of the field.
+     * @throws NullPointerException
+     *             if {@code name} or {@code cl} is {@code null}.
      */
     public ObjectStreamField(String name, Class<?> cl) {
         if (name == null || cl == null) {
@@ -84,14 +86,19 @@
     }
 
     /**
-     * Constructs an ObjectStreamField with the given name and the given type
+     * Constructs an ObjectStreamField with the specified name, type and the
+     * indication if it is unshared.
      * 
      * @param name
-     *            a String, the name of the field
+     *            the name of the field.
      * @param cl
-     *            A Class object representing the type of the field
+     *            the type of the field.
      * @param unshared
-     *            write and read the field unshared
+     *            {@code true} if the field is written and read unshared;
+     *            {@code false} otherwise.
+     * @throws NullPointerException
+     *             if {@code name} or {@code cl} is {@code null}.
+     * @see ObjectOutputStream#writeUnshared(Object)
      */
     public ObjectStreamField(String name, Class<?> cl, boolean unshared) {
         if (name == null || cl == null) {
@@ -122,15 +129,16 @@
     }
 
     /**
-     * Comparing the receiver to the parameter, according to the Comparable
-     * interface.
+     * Compares this field descriptor to the specified one. Checks first if one
+     * of the compared fields has a primitive type and the other one not. If so,
+     * the field with the primitive type is considered to be "smaller". If both
+     * fields are equal, their names are compared.
      * 
      * @param o
-     *            The object to compare against
-     * 
-     * @return -1 if the receiver is "smaller" than the parameter. 0 if the
-     *         receiver is "equal" to the parameter. 1 if the receiver is
-     *         "greater" than the parameter.
+     *            the object to compare with.
+     * @return -1 if this field is "smaller" than field {@code o}, 0 if both
+     *         fields are equal; 1 if this field is "greater" than field {@code
+     *         o}.
      */
     public int compareTo(Object o) {
         ObjectStreamField f = (ObjectStreamField) o;
@@ -158,18 +166,18 @@
     }
 
     /**
-     * Return the name of the field the receiver represents
+     * Gets the name of this field.
      * 
-     * @return a String, the name of the field
+     * @return the field's name.
      */
     public String getName() {
         return name;
     }
 
     /**
-     * Return the offset of this field in the object
+     * Gets the offset of this field in the object.
      * 
-     * @return an int, the offset
+     * @return this field's offset.
      */
     public int getOffset() {
         return offset;
@@ -189,9 +197,9 @@
     }
 
     /**
-     * Return the type of the field the receiver represents
+     * Gets the type of this field.
      * 
-     * @return A Class object representing the type of the field
+     * @return a {@code Class} object representing the type of the field.
      */
     public Class<?> getType() {
         Class<?> cl = getTypeInternal();
@@ -202,10 +210,23 @@
     }
 
     /**
-     * Return the type code that corresponds to the class the receiver
-     * represents
+     * Gets a character code for the type of this field. The following codes are
+     * used:
      * 
-     * @return A char, the typecode of the class
+     * <pre>
+     * B     byte
+     * C     char
+     * D     double
+     * F     float
+     * I     int
+     * J     long
+     * L     class or interface
+     * S     short
+     * Z     boolean
+     * [     array
+     * </pre>
+     *
+     * @return the field's type code.
      */
     public char getTypeCode() {
         Class<?> t = getTypeInternal();
@@ -240,10 +261,11 @@
     }
 
     /**
-     * Return the type signature used by the VM to represent the type for this
+     * Gets the type signature used by the VM to represent the type of this
      * field.
      * 
-     * @return A String, the signature for the class of this field.
+     * @return the signature of this field's class or {@code null} if this
+     *         field's type is primitive.
      */
     public String getTypeString() {
         if (isPrimitive()) {
@@ -259,11 +281,10 @@
     }
 
     /**
-     * Return a boolean indicating whether the class of this field is a
-     * primitive type or not
+     * Indicates whether this field's type is a primitive type.
      * 
-     * @return true if the type of this field is a primitive type false if the
-     *         type of this field is a regular class.
+     * @return {@code true} if this field's type is primitive; {@code false} if
+     *         the type of this field is a regular class.
      */
     public boolean isPrimitive() {
         Class<?> t = getTypeInternal();
@@ -271,20 +292,20 @@
     }
 
     /**
-     * Set the offset this field represents in the object
+     * Sets this field's offset in the object.
      * 
      * @param newValue
-     *            an int, the offset
+     *            the field's new offset.
      */
     protected void setOffset(int newValue) {
         this.offset = newValue;
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
+     * Returns a string containing a concise, human-readable description of this
+     * field descriptor.
      * 
-     * @return a printable representation for the receiver.
+     * @return a printable representation of this descriptor.
      */
     @Override
     public String toString() {
@@ -355,9 +376,9 @@
     }
 
     /**
-     * Answers whether this serialized field is unshared.
+     * Indicats whether this field is unshared.
      * 
-     * @return true if the field is unshared, false otherwise.
+     * @return {@code true} if this field is unshared, {@code false} otherwise.
      */
     public boolean isUnshared() {
         return unshared;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OptionalDataException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OptionalDataException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OptionalDataException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OptionalDataException.java Fri May  1 08:08:59 2009
@@ -18,8 +18,9 @@
 package java.io;
 
 /**
- * When readObject() encounters primitive types (int, char, etc) instead of an
- * object instance in the input stream, this type of exception will be thrown.
+ * Signals that the {@link ObjectInputStream} class encountered a primitive type
+ * ({@code int}, {@code char} etc.) instead of an object instance in the input
+ * stream.
  * 
  * @see ObjectInputStream#available()
  * @see ObjectInputStream#readObject()
@@ -30,28 +31,30 @@
     private static final long serialVersionUID = -8011121865681257820L;
 
     /**
-     * If true it means there is no more primitive data available.
+     * {@code true} indicates that there is no more primitive data available.
      */
     public boolean eof;
 
     /**
-     * Number of bytes of primitive data (int, char, long, etc).
+     * The number of bytes of primitive data (int, char, long etc.) that are
+     * available.
      */
     public int length;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code OptionalDataException} with its stack trace
+     * filled in.
      */
     OptionalDataException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code OptionalDataException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     OptionalDataException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStream.java Fri May  1 08:08:59 2009
@@ -20,8 +20,18 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * OutputStream is an abstract class for all byte output streams. It provides
- * basic method implementations for writing bytes to a stream.
+ * The base class for all output streams. An output stream is a means of writing
+ * data to a target in a byte-wise manner. Most output streams expect the
+ * {@link #flush()} method to be called before closing the stream, to ensure all
+ * data is actually written through.
+ * <p>
+ * This abstract class does not provide a fully working implementation, so it
+ * needs to be subclassed, and at least the {@link #write(int)} method needs to
+ * be overridden. Overriding some of the non-abstract methods is also often
+ * advised, since it might result in higher efficiency.
+ * <p>
+ * Many specialized output streams for purposes like writing to a file already
+ * exist in this package.
  * 
  * @see InputStream
  */
@@ -35,58 +45,57 @@
     }
 
     /**
-     * Close this OutputStream. Concrete implementations of this class should
-     * free any resources during close. This implementation does nothing.
+     * Closes this stream. Implementations of this method should free any
+     * resources used by the stream. This implementation does nothing.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this OutputStream.
+     *             if an error occurs while closing this stream.
      */
     public void close() throws IOException {
         /* empty */
     }
 
     /**
-     * Flush this OutputStream. Concrete implementations of this class should
-     * ensure any pending writes to the underlying stream are written out when
-     * this method is envoked. This implementation does nothing.
+     * Flushes this stream. Implementations of this method should ensure that
+     * any buffered data is written out. This implementation does nothing.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this OutputStream.
+     *             if an error occurs while flushing this stream.
      */
     public void flush() throws IOException {
         /* empty */
     }
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to
-     * this OutputStream.
+     * Writes the entire contents of the byte array {@code buffer} to this
+     * stream.
      * 
      * @param buffer
-     *            the buffer to be written
-     * 
+     *            the buffer to be written.
      * @throws IOException
-     *             If an error occurs attempting to write to this OutputStream.
+     *             if an error occurs while writing to this stream.
      */
     public void write(byte buffer[]) throws IOException {
         write(buffer, 0, buffer.length);
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at <code>offset</code> to this
-     * OutputStream.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * position {@code offset} to this stream.
      * 
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to be written.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the start position in {@code buffer} from where to get bytes.
      * @param count
-     *            number of bytes in buffer to write
-     * 
+     *            the number of bytes from {@code buffer} to write to this
+     *            stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this OutputStream.
+     *             if an error occurs while writing to this stream.
      * @throws IndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *             if {@code offset < 0} or {@code count < 0}, or if
+     *             {@code offset + count} is bigger than the length of
+     *             {@code buffer}.
      */
     public void write(byte buffer[], int offset, int count) throws IOException {
         // avoid int overflow, check null buffer
@@ -100,14 +109,13 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this OutputStream.
-     * Only the low order byte of <code>oneByte</code> is written.
+     * Writes a single byte to this stream. Only the least significant byte of
+     * the integer {@code oneByte} is written to the stream.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to be written.
      * @throws IOException
-     *             If an error occurs attempting to write to this OutputStream.
+     *             if an error occurs while writing to this stream.
      */
     public abstract void write(int oneByte) throws IOException;
 }



Mime
View raw message