harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [5/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/LineNumberReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberReader.java Fri May  1 08:08:59 2009
@@ -18,11 +18,10 @@
 package java.io;
 
 /**
- * LineNumberReader is a buffered character input reader which counts line
- * numbers as data is being read. The line number starts at 0 and is incremented
- * any time '\r', '\n', or '\r\n' is read.
- * 
- * @see BufferedWriter
+ * Wraps an existing {@link Reader} and counts the line terminators encountered
+ * while reading the data. The line number starts at 0 and is incremented any
+ * time {@code '\r'}, {@code '\n'} or {@code "\r\n"} is read. The class has an
+ * internal buffer for its data. The size of the buffer defaults to 8 KB.
  */
 public class LineNumberReader extends BufferedReader {
 
@@ -35,36 +34,35 @@
     private boolean markedLastWasCR;
 
     /**
-     * Constructs a new buffered LineNumberReader on the Reader <code>in</code>.
-     * The default buffer size (8K) is allocated and all reads can now be
-     * filtered through this LineNumberReader.
+     * Constructs a new LineNumberReader on the Reader {@code in}. The internal
+     * buffer gets the default size (8 KB).
      * 
      * @param in
-     *            the Reader to buffer reads on.
+     *            the Reader that is buffered.
      */
     public LineNumberReader(Reader in) {
         super(in);
     }
 
     /**
-     * Constructs a new buffered LineNumberReader on the Reader <code>in</code>.
-     * The buffer size is specified by the parameter <code>size</code> and all
-     * reads can now be filtered through this LineNumberReader.
+     * Constructs a new LineNumberReader on the Reader {@code in}. The size of
+     * the internal buffer is specified by the parameter {@code size}.
      * 
      * @param in
-     *            the Reader to buffer reads on.
+     *            the Reader that is buffered.
      * @param size
-     *            the size of buffer to allocate.
+     *            the size of the buffer to allocate.
+     * @throws IllegalArgumentException
+     *             if {@code size <= 0}.
      */
     public LineNumberReader(Reader in, int size) {
         super(in, size);
     }
 
     /**
-     * Answers a int representing the current line number for this
-     * LineNumberReader.
+     * Returns the current line number for this reader. Numbering starts at 0.
      * 
-     * @return int the current line number.
+     * @return the current line number.
      */
     public int getLineNumber() {
         synchronized (lock) {
@@ -73,20 +71,20 @@
     }
 
     /**
-     * Set a Mark position in this LineNumberReader. The parameter
-     * <code>readLimit</code> indicates how many characters can be read before
-     * a mark is invalidated. Sending reset() will reposition the reader back to
-     * the marked position provided <code>readLimit</code> has not been
-     * surpassed. The lineNumber associated with this marked position will also
-     * be saved and restored when reset() is sent provided
-     * <code>readLimit</code> has not been surpassed.
+     * Sets a mark position in this reader. The parameter {@code readlimit}
+     * indicates how many characters can be read before the mark is invalidated.
+     * Sending {@code reset()} will reposition this reader back to the marked
+     * position, provided that {@code readlimit} has not been surpassed. The
+     * line number associated with this marked position is also stored so that
+     * it can be restored when {@code reset()} is called.
      * 
      * @param readlimit
-     *            an int representing how many characters must be read before
-     *            invalidating the mark.
-     * 
+     *            the number of characters that can be read from this stream
+     *            before the mark is invalidated.
      * @throws IOException
-     *             If an error occurs attempting mark this LineNumberReader.
+     *             if an error occurs while setting the mark in this reader.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public void mark(int readlimit) throws IOException {
@@ -98,18 +96,19 @@
     }
 
     /**
-     * Reads a single char from this LineNumberReader and returns the result as
-     * an int. The low-order 2 bytes are returned or -1 of the end of reader was
-     * encountered. This implementation returns a char from the target reader.
+     * Reads a single character from the source reader and returns it as an
+     * integer with the two higher-order bytes set to 0. Returns -1 if the end
+     * of the source reader has been reached.
+     * <p>
      * The line number count is incremented if a line terminator is encountered.
-     * A line delimiter sequence is determined by '\r', '\n', or '\r\n'. In this
-     * method, the sequence is always translated into '\n'.
-     * 
-     * @return int The char read or -1 if end of reader.
-     * 
+     * Recognized line terminator sequences are {@code '\r'}, {@code '\n'} and
+     * {@code "\r\n"}. Line terminator sequences are always translated into
+     * {@code '\n'}.
+     *
+     * @return the character read or -1 if the end of the source reader has been
+     *         reached.
      * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *             if the reader is closed or another IOException occurs.
      */
     @SuppressWarnings("fallthrough")
     @Override
@@ -133,28 +132,28 @@
     }
 
     /**
-     * Reads at most <code>count</code> chars from this LineNumberReader and
-     * stores them in char array <code>buffer</code> starting at offset
-     * <code>offset</code>. Answer the number of chars actually read or -1 if
-     * no chars were read and end of reader was encountered. This implementation
-     * reads chars from the target stream. The line number count is incremented
-     * if a line terminator is encountered. A line delimiter sequence is
-     * determined by '\r', '\n', or '\r\n'. In this method, the sequence is
-     * always translated into '\n'.
-     * 
+     * Reads at most {@code count} characters from the source reader and stores
+     * them in the character array {@code buffer} starting at {@code offset}.
+     * Returns the number of characters actually read or -1 if no characters
+     * have been read and the end of this reader has been reached.
+     * <p>
+     * The line number count is incremented if a line terminator is encountered.
+     * Recognized line terminator sequences are {@code '\r'}, {@code '\n'} and
+     * {@code "\r\n"}. Line terminator sequences are always translated into
+     * {@code '\n'}.
+     *
      * @param buffer
-     *            the char array in which to store the read chars.
+     *            the array in which to store the characters read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read chars.
+     *            the initial position in {@code buffer} to store the characters
+     *            read from this reader.
      * @param count
-     *            the maximum number of chars to store in <code>buffer</code>.
-     * @return the number of chars actually read or -1 if end of reader.
-     * 
+     *            the maximum number of characters to store in {@code buffer}.
+     * @return the number of characters actually read or -1 if the end of the
+     *         source reader has been reached while reading.
      * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *             if this reader is closed or another IOException occurs.
      */
-
     @Override
     public int read(char[] buffer, int offset, int count) throws IOException {
         synchronized (lock) {
@@ -181,18 +180,15 @@
     }
 
     /**
-     * Answers a <code>String</code> representing the next line of text
-     * available in this LineNumberReader. A line is represented by 0 or more
-     * characters followed by <code>'\n'</code>, <code>'\r'</code>,
-     * <code>"\n\r"</code> or end of stream. The <code>String</code> does
-     * not include the newline sequence.
-     * 
-     * @return String the contents of the line or null if no characters were
-     *         read before end of stream.
+     * Returns the next line of text available from this reader. A line is
+     * represented by 0 or more characters followed by {@code '\r'},
+     * {@code '\n'}, {@code "\r\n"} or the end of the stream. The returned
+     * string does not include the newline sequence.
      * 
+     * @return the contents of the line or {@code null} if no characters have
+     *         been read before the end of the stream has been reached.
      * @throws IOException
-     *             If the LineNumberReader is already closed or some other IO
-     *             error occurs.
+     *             if this reader is closed or another IOException occurs.
      */
     @Override
     public String readLine() throws IOException {
@@ -203,15 +199,16 @@
     }
 
     /**
-     * Reset this LineNumberReader to the last marked location. If the
-     * <code>readlimit</code> has been passed or no <code>mark</code> has
-     * been set, throw IOException. This implementation resets the target
-     * reader. It also resets the line count to what is was when this reader was
-     * marked.
+     * Resets this reader to the last marked location. It also resets the line
+     * count to what is was when this reader was marked. This implementation
+     * resets the source reader.
      * 
      * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *             if this reader is already closed, no mark has been set or the
+     *             mark is no longer valid because more than {@code readlimit}
+     *             bytes have been read since setting the mark.
+     * @see #mark(int)
+     * @see #markSupported()
      */
     @Override
     public void reset() throws IOException {
@@ -223,12 +220,14 @@
     }
 
     /**
-     * Sets the lineNumber of this LineNumberReader to the specified
-     * <code>lineNumber</code>. Note that this may have side effects on the
-     * line number associated with the last marked position.
+     * Sets the line number of this reader to the specified {@code lineNumber}.
+     * Note that this may have side effects on the line number associated with
+     * the last marked position.
      * 
      * @param lineNumber
-     *            the new lineNumber value.
+     *            the new line number value.
+     * @see #mark(int)
+     * @see #reset()
      */
     public void setLineNumber(int lineNumber) {
         synchronized (lock) {
@@ -237,19 +236,22 @@
     }
 
     /**
-     * Skips <code>count</code> number of chars in this LineNumberReader.
-     * Subsequent <code>read()</code>'s will not return these chars unless
-     * <code>reset()</code> is used. This implementation skips
-     * <code>count</code> number of chars in the target stream and increments
-     * the lineNumber count as chars are skipped.
+     * Skips {@code count} number of characters in this reader. Subsequent
+     * {@code read()}'s will not return these characters unless {@code reset()}
+     * is used. This implementation skips {@code count} number of characters in
+     * the source reader and increments the line number count whenever line
+     * terminator sequences are skipped.
      * 
      * @param count
-     *            the number of chars to skip.
-     * @return the number of chars actually skipped.
-     * 
-     * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *            the number of characters to skip.
+     * @return the number of characters actually skipped.
+     * @throws IllegalArgumentException
+     *             if {@code count < 0}.
+     * @throws IOException
+     *             if this reader is closed or another IOException occurs.
+     * @see #mark(int)
+     * @see #read()
+     * @see #reset()
      */
     @Override
     public long skip(long count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotActiveException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotActiveException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotActiveException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotActiveException.java Fri May  1 08:08:59 2009
@@ -18,37 +18,36 @@
 package java.io;
 
 /**
- * Some methods in ObjectInputStream and ObjectOutputStream can only be called
- * from a nested call to readObject() or writeObject(). Any attempt to call them
- * from another context will cause this exception to be thrown. The list of
- * methods that are protected this way is:
+ * Signals that a serialization-related method has been invoked in the wrong
+ * place. Some methods in {@code ObjectInputStream} and {@code
+ * ObjectOutputStream} can only be called from a nested call to readObject() or
+ * writeObject(). Any attempt to call them from another context will cause a
+ * {@code NotActiveException} to be thrown. The list of methods that are
+ * protected this way is:
  * <ul>
- * <li>ObjectInputStream.defaultReadObject()</li>
- * <li>ObjectInputStream.registerValidation()</li>
- * <li>ObjectOutputStream.defaultWriteObject()</li>
+ * <li>{@link ObjectInputStream#defaultReadObject()}</li>
+ * <li>{@link ObjectInputStream#registerValidation(ObjectInputValidation, int)}</li>
+ * <li>{@link ObjectOutputStream#defaultWriteObject()}</li>
  * </ul>
- * 
- * @see ObjectInputStream#defaultReadObject()
- * @see ObjectInputStream#registerValidation(ObjectInputValidation, int)
- * @see ObjectOutputStream#defaultWriteObject()
  */
 public class NotActiveException extends ObjectStreamException {
 
     private static final long serialVersionUID = -3893467273049808895L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code NotActiveException} with its stack trace filled
+     * in.
      */
     public NotActiveException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code NotActiveException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public NotActiveException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotSerializableException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotSerializableException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotSerializableException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotSerializableException.java Fri May  1 08:08:59 2009
@@ -18,34 +18,33 @@
 package java.io;
 
 /**
- * When an implementation of ObjectOutput.writeObject() is passed an object that
- * is not serializable, it will throw this type of exception. This can happen if
- * the object does not implement Serializable or Externalizable, or if it is
- * Serializable but it overrides writeObject(ObjectOutputStream) and explicitely
- * decides it wants to prevent serialization, by throwing this type of
- * exception.
+ * Signals that an object that is not serializable has been passed into the
+ * {@code ObjectOutput.writeObject()} mthod. This can happen if the object does
+ * not implement {@code Serializable} or {@code Externalizable}, or if it is
+ * serializable but it overrides {@code writeObject(ObjectOutputStream)} and
+ * explicitly prevents serialization by throwing this type of exception.
  * 
- * @see ObjectOutputStream#writeObject(Object)
  * @see ObjectOutput#writeObject(Object)
+ * @see ObjectOutputStream#writeObject(Object)
  */
 public class NotSerializableException extends ObjectStreamException {
 
     private static final long serialVersionUID = 2906642554793891381L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
-     * 
+     * Constructs a new {@code NotSerializableException} with its stack trace
+     * filled in.
      */
     public NotSerializableException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@link NotSerializableException} with its stack trace
+     * and detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public NotSerializableException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInput.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInput.java Fri May  1 08:08:59 2009
@@ -18,104 +18,97 @@
 package java.io;
 
 /**
- * Streams to be used with serialization to read objects must implement this
- * interface. ObjectInputStream is one example.
+ * Defines an interface for classes that allow reading serialized objects.
  * 
  * @see ObjectInputStream
  * @see ObjectOutput
  */
 public interface ObjectInput extends DataInput {
     /**
-     * Answers a int representing then number of bytes of primitive data that
-     * are available.
-     * 
-     * @return int the number of primitive bytes available.
+     * Indicates the number of bytes of primitive data that can be read without
+     * blocking.
      * 
+     * @return the number of bytes available.
      * @throws IOException
-     *             If an error occurs in this ObjectInput.
+     *             if an I/O error occurs.
      */
     public int available() throws IOException;
 
     /**
-     * Close this ObjectInput. Concrete implementations of this class should
-     * free any resources during close.
+     * Closes this stream. Implementations of this method should free any
+     * resources used by the stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this ObjectInput.
+     *             if an I/O error occurs while closing the input stream.
      */
     public void close() throws IOException;
 
     /**
-     * Reads a single byte from this ObjectInput and returns the result as an
-     * int. The low-order byte is returned or -1 of the end of stream was
-     * encountered.
-     * 
-     * @return int The byte read or -1 if end of ObjectInput.
+     * Reads a single byte from this stream and returns it as an integer in the
+     * range from 0 to 255. Returns -1 if the end of this stream has been
+     * reached. Blocks if no input is available.
      * 
+     * @return the byte read or -1 if the end of this stream has been reached.
      * @throws IOException
-     *             If the ObjectInput is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     public int read() throws IOException;
 
     /**
-     * Reads bytes from the <code>ObjectInput</code> and stores them in byte
-     * array <code>buffer</code>. Blocks while waiting for input.
+     * Reads bytes from this stream into the byte array {@code buffer}. Blocks
+     * while waiting for input.
      * 
      * @param buffer
-     *            the array in which to store the read bytes.
-     * @return how many bytes were read or <code>-1</code> if encountered end
-     *         of <code>ObjectInput</code>.
-     * 
+     *            the array in which to store the bytes read.
+     * @return the number of bytes read or -1 if the end of this stream has been
+     *         reached.
      * @throws IOException
-     *             If the <code>ObjectInput</code> is already closed or
-     *             another IOException occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     public int read(byte[] buffer) throws IOException;
 
     /**
-     * Reads at most <code>count</code> bytes from the ObjectInput and stores
-     * them in byte array <code>buffer</code> starting at offset
-     * <code>count</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of ObjectInput was encountered.
+     * Reads at most {@code count} bytes from this stream and stores them in
+     * byte array {@code buffer} starting at offset {@code count}. Blocks while
+     * waiting for input.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the array in which to store the bytes read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read bytes.
+     *            the initial position in {@code buffer} to store the bytes read
+     *            from this stream.
      * @param count
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * @return the number of bytes actually read or -1 if end of ObjectInput.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes read or -1 if the end of this stream has been
+     *         reached.
      * @throws IOException
-     *             If the ObjectInput is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     public int read(byte[] buffer, int offset, int count) throws IOException;
 
     /**
-     * Reads the next object from this ObjectInput.
+     * Reads the next object from this stream.
      * 
-     * @return the next object read from this ObjectInput
+     * @return the object read.
      * 
-     * @throws IOException
-     *             If an error occurs attempting to read from this ObjectInput.
      * @throws ClassNotFoundException
-     *             If the object's class cannot be found
+     *             if the object's class cannot be found.
+     * @throws IOException
+     *             if this stream is closed or another I/O error occurs.
      */
     public Object readObject() throws ClassNotFoundException, IOException;
 
     /**
-     * Skips <code>toSkip</code> number of bytes in this ObjectInput.
-     * Subsequent <code>read()</code>'s will not return these bytes.
+     * Skips {@code toSkip} bytes on this stream. Less than {@code toSkip} byte are
+     * skipped if the end of this stream is reached before the operation
+     * completes.
      * 
      * @param toSkip
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
      * 
      * @throws IOException
-     *             If the ObjectInput is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     public long skip(long toSkip) throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputStream.java Fri May  1 08:08:59 2009
@@ -39,10 +39,9 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * An ObjectInputStream can be used to load Java objects from a stream where the
- * objects were saved using an ObjectOutputStream. Primitive data (ints, bytes,
- * chars, etc) can also be loaded if the data was saved as primitive types as
- * well. It is invalid to attempt to read an object as primitive data.
+ * A specialized {@link InputStream} that is able to read (deserialize) Java
+ * objects as well as primitive data types (int, byte, char etc.). The data has
+ * typically been saved using an ObjectOutputStream.
  * 
  * @see ObjectOutputStream
  * @see ObjectInput
@@ -132,134 +131,225 @@
     }
 
     /**
-     * Inner class to provide access to serializable fields
+     * GetField is an inner class that provides access to the persistent fields
+     * read from the source stream.
      */
     public abstract static class GetField {
         /**
-         * @return ObjectStreamClass
+         * Gets the ObjectStreamClass that describes a field.
+         *
+         * @return the descriptor class for a serialized field.
          */
         public abstract ObjectStreamClass getObjectStreamClass();
 
         /**
+         * Indicates if the field identified by {@code name} is defaulted. This
+         * means that it has no value in this stream.
+         *
          * @param name
-         * @return <code>true</code> if the default value is set,
-         *         <code>false</code> otherwise
-         * 
-         * @throws IOException
+         *            the name of the field to check.
+         * @return {@code true} if the field is defaulted, {@code false}
+         *         otherwise.
          * @throws IllegalArgumentException
+         *             if {@code name} does not identify a serializable field.
+         * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          */
         public abstract boolean defaulted(String name) throws IOException,
                 IllegalArgumentException;
 
         /**
+         * Gets the value of the boolean field identified by {@code name} from
+         * the persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code boolean}.
          */
         public abstract boolean get(String name, boolean defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the character field identified by {@code name} from
+         * the persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code char}.
          */
         public abstract char get(String name, char defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the byte field identified by {@code name} from the
+         * persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code byte}.
          */
         public abstract byte get(String name, byte defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the short field identified by {@code name} from the
+         * persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code short}.
          */
         public abstract short get(String name, short defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the integer field identified by {@code name} from
+         * the persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code int}.
          */
         public abstract int get(String name, int defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the long field identified by {@code name} from the
+         * persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code long}.
          */
         public abstract long get(String name, long defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the float field identified by {@code name} from the
+         * persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code float} is
+         *             not {@code char}.
          */
         public abstract float get(String name, float defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the double field identified by {@code name} from
+         * the persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code double}.
          */
         public abstract double get(String name, double defaultValue)
                 throws IOException, IllegalArgumentException;
 
         /**
+         * Gets the value of the object field identified by {@code name} from
+         * the persistent field.
+         *
          * @param name
+         *            the name of the field to get.
          * @param defaultValue
-         * @return the value
-         * 
+         *            the default value that is used if the field does not have
+         *            a value when read from the source stream.
+         * @return the value of the field identified by {@code name}.
          * @throws IOException
+         *             if an error occurs while reading from the source input
+         *             stream.
          * @throws IllegalArgumentException
+         *             if the type of the field identified by {@code name} is
+         *             not {@code Object}.
          */
         public abstract Object get(String name, Object defaultValue)
                 throws IOException, IllegalArgumentException;
     }
 
     /**
-     * Constructs a new ObjectInputStream. The representation and proper
-     * initialization is on the hands of subclasses.
+     * Constructs a new ObjectInputStream. 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 not called from a subclass
+     *             if an error occurs when creating this stream.
      * @throws SecurityException
-     *             If subclasses are not allowed
-     * 
+     *             if a security manager is installed and it denies subclassing
+     *             this class.
      * @see SecurityManager#checkPermission(java.security.Permission)
      */
     protected ObjectInputStream() throws IOException, SecurityException {
@@ -274,17 +364,19 @@
     }
 
     /**
-     * Constructs a new ObjectInputStream on the InputStream <code>input</code>.
-     * All reads are now filtered through this stream.
+     * Constructs a new ObjectInputStream that reads from the InputStream
+     * {@code input}.
      * 
      * @param input
-     *            The non-null InputStream to filter reads on.
-     * 
+     *            the non-null source InputStream to filter reads on.
      * @throws IOException
-     *             If an IO exception happened when reading the stream header.
+     *             if an error occurs while reading the stream header.
      * @throws StreamCorruptedException
-     *             If the underlying stream does not contain serialized objects
-     *             that can be read.
+     *             if the source stream does not contain serialized objects that
+     *             can be read.
+     * @throws SecurityException
+     *             if a security manager is installed and it denies subclassing
+     *             this class.
      */
     public ObjectInputStream(InputStream input)
             throws StreamCorruptedException, IOException {
@@ -339,15 +431,14 @@
     }
 
     /**
-     * Returns the number of bytes of primitive data available from the
-     * receiver. It should not be used at any arbitrary position; just when
-     * reading primitive data types (ints, chars, etc).
-     * 
-     * @return the number of available primitive data bytes
+     * Returns the number of bytes of primitive data that can be read from this
+     * stream without blocking. This method should not be used at any arbitrary
+     * position; just when reading primitive data types (int, char etc).
      * 
+     * @return the number of available primitive data bytes.
      * @throws IOException
-     *             If any IO problem occurred when trying to compute the bytes
-     *             available.
+     *             if any I/O problem occurs while computing the available
+     *             bytes.
      */
     @Override
     public int available() throws IOException {
@@ -357,9 +448,9 @@
     }
 
     /**
-     * Checks to see if it is ok to read primitive types at this point from the
-     * receiver. One is not supposed to read primitive types when about to read
-     * an object, for example, so an exception has to be thrown.
+     * Checks to if it is ok to read primitive types from this stream at
+     * this point. One is not supposed to read primitive types when about to
+     * read an object, for example, so an exception has to be thrown.
      * 
      * @throws IOException
      *             If any IO problem occurred when trying to read primitive type
@@ -403,11 +494,10 @@
     }
 
     /**
-     * Close this ObjectInputStream. This implementation closes the target
-     * stream.
+     * Closes this stream. This implementation closes the source 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 {
@@ -415,16 +505,16 @@
     }
 
     /**
-     * Default method to read objects from the receiver. Fields defined in the
-     * object's class and super classes (which are Serializable) will be read.
+     * Default method to read objects from this stream. Serializable fields
+     * defined in the object's class and superclasses are read from the source
+     * stream.
      * 
-     * @throws IOException
-     *             If an IO error occurs attempting to read the object data
      * @throws ClassNotFoundException
-     *             If the class of the object cannot be found
+     *             if the object's class cannot be found.
+     * @throws IOException
+     *             if an I/O error occurs while reading the object data.
      * @throws NotActiveException
-     *             If this method is not called from readObject()
-     * 
+     *             if this method is not called from {@code readObject()}.
      * @see ObjectOutputStream#defaultWriteObject
      */
     public void defaultReadObject() throws IOException, ClassNotFoundException,
@@ -438,17 +528,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 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 #resolveObject
      * @see ObjectOutputStream#enableReplaceObject
      */
@@ -468,15 +558,14 @@
     }
 
     /**
-     * Checks if two classes belong to the same package and returns true in the
-     * positive case. Return false otherwise.
+     * Checks if two classes belong to the same package.
      * 
      * @param c1
-     *            one of the classes to test
+     *            one of the classes to test.
      * @param c2
-     *            the other class to test
-     * @return <code>true</code> if the two classes belong to the same
-     *         package, <code>false</code> otherwise
+     *            the other class to test.
+     * @return {@code true} if the two classes belong to the same package,
+     *         {@code false} otherwise.
      */
     private boolean inSamePackage(Class<?> c1, Class<?> c2) {
         String nameC1 = c1.getName();
@@ -495,7 +584,7 @@
     }
 
     /**
-     * Return the next <code>Integer</code> handle to be used to indicate cyclic
+     * Return the next {@code int} handle to be used to indicate cyclic
      * references being loaded from the stream.
      * 
      * @return the next handle to represent the next cyclic reference
@@ -534,14 +623,14 @@
     }
 
     /**
-     * Reads a single byte from the receiver and returns the result as an int.
-     * The low-order byte is returned or -1 of the end of stream was
-     * encountered.
-     * 
-     * @return The byte read or -1 if end of stream.
+     * Reads a single byte from the source stream and returns it as an integer
+     * in the range from 0 to 255. Returns -1 if the end of the source stream
+     * has been reached. Blocks if no input is available.
      * 
+     * @return the byte read or -1 if the end of the source stream has been
+     *         reached.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from this stream.
      */
     @Override
     public int read() throws IOException {
@@ -550,21 +639,28 @@
     }
 
     /**
-     * Reads at most <code>length</code> bytes from the receiver and stores
-     * them in byte array <code>buffer</code> starting at offset
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of stream was encountered.
+     * Reads at most {@code length} bytes from the source stream and stores them
+     * in byte array {@code buffer} starting at offset {@code count}. Blocks
+     * until {@code count} bytes have been read, the end of the source stream is
+     * detected or an exception is thrown.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the array in which to store the bytes read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read bytes.
+     *            the initial position in {@code buffer} to store the bytes
+     *            read from the source stream.
      * @param length
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * @return The number of bytes actually read or -1 if end of stream.
-     * 
-     * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes read or -1 if the end of the source input
+     *         stream has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code buffer}.
+     * @throws IOException
+     *             if an error occurs while reading from this stream.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     @Override
     public int read(byte[] buffer, int offset, int length) throws IOException {
@@ -586,7 +682,7 @@
     /**
      * Reads and returns an array of raw bytes with primitive data. The array
      * will have up to 255 bytes. The primitive data will be in the format
-     * described by <code>DataOutputStream</code>.
+     * described by {@code DataOutputStream}.
      * 
      * @return The primitive data read, as raw bytes
      * 
@@ -602,7 +698,7 @@
     /**
      * Reads and returns an array of raw bytes with primitive data. The array
      * will have more than 255 bytes. The primitive data will be in the format
-     * described by <code>DataOutputStream</code>.
+     * described by {@code DataOutputStream}.
      * 
      * @return The primitive data read, as raw bytes
      * 
@@ -616,39 +712,42 @@
     }
 
     /**
-     * Reads and returns primitive data of type boolean read from the receiver
-     * 
-     * @return A boolean saved as primitive data using
-     *         <code>ObjectOutputStream.writeBoolean()</code>
+     * Reads a boolean from the source stream.
      * 
+     * @return the boolean value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public boolean readBoolean() throws IOException {
         return primitiveTypes.readBoolean();
     }
 
     /**
-     * Reads and returns primitive data of type byte read from the receiver
-     * 
-     * @return A byte saved as primitive data using
-     *         <code>ObjectOutputStream.writeByte()</code>
+     * Reads a byte (8 bit) from the source stream.
      * 
+     * @return the byte value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public byte readByte() throws IOException {
         return primitiveTypes.readByte();
     }
 
     /**
-     * Reads and returns primitive data of type char read from the receiver
-     * 
-     * @return A char saved as primitive data using
-     *         <code>ObjectOutputStream.writeChar()</code>
+     * Reads a character (16 bit) from the source stream.
      * 
+     * @return the char value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public char readChar() throws IOException {
         return primitiveTypes.readChar();
@@ -679,7 +778,7 @@
     }
 
     /**
-     * Reads a class descriptor (an <code>ObjectStreamClass</code>) from the
+     * Reads a class descriptor (an {@code ObjectStreamClass}) from the
      * stream.
      * 
      * @return the class descriptor read from the stream
@@ -717,7 +816,7 @@
 
     /**
      * Reads the content of the receiver based on the previously read token
-     * <code>tc</code>.
+     * {@code tc}.
      * 
      * @param tc
      *            The token code for the next item in the stream
@@ -767,7 +866,7 @@
 
     /**
      * Reads the content of the receiver based on the previously read token
-     * <code>tc</code>. Primitive data content is considered an error.
+     * {@code tc}. Primitive data content is considered an error.
      * 
      * @param unshared
      *            read the object unshared
@@ -851,13 +950,14 @@
     }
 
     /**
-     * Reads and returns primitive data of type double read from the receiver
-     * 
-     * @return A double saved as primitive data using
-     *         <code>ObjectOutputStream.writeDouble()</code>
+     * Reads a double (64 bit) from the source stream.
      * 
+     * @return the double value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public double readDouble() throws IOException {
         return primitiveTypes.readDouble();
@@ -907,10 +1007,10 @@
 
     /**
      * Reads a collection of field descriptors (name, type name, etc) for the
-     * class descriptor <code>cDesc</code> (an <code>ObjectStreamClass</code>)
+     * class descriptor {@code cDesc} (an {@code ObjectStreamClass})
      * 
      * @param cDesc
-     *            The class descriptor (an <code>ObjectStreamClass</code>)
+     *            The class descriptor (an {@code ObjectStreamClass})
      *            for which to write field information
      * 
      * @throws IOException
@@ -987,20 +1087,20 @@
     }
 
     /**
-     * Reads the fields of the object being read from the stream. The stream
-     * will use the currently active <code>getField</code> object, allowing
-     * users to load emulated fields, for cross-loading compatibility when a
-     * class definition changes.
+     * Reads the persistent fields of the object that is currently being read
+     * from the source stream. The values read are stored in a GetField object
+     * that provides access to the persistent fields. This GetField object is
+     * then returned.
      * 
-     * @return the fields being read
-     * 
-     * @throws IOException
-     *             If an IO exception happened
+     * @return the GetField object from which persistent fields can be accessed
+     *         by name.
      * @throws ClassNotFoundException
-     *             If a class of an object being de-serialized can not be found
+     *             if the class of an object being deserialized can not be
+     *             found.
+     * @throws IOException
+     *             if an error occurs while reading from this stream.
      * @throws NotActiveException
-     *             If there is no object currently being loaded (invalid to call
-     *             this method)
+     *             if this stream is currently not reading an object.
      */
     public GetField readFields() throws IOException, ClassNotFoundException,
             NotActiveException {
@@ -1016,11 +1116,11 @@
 
     /**
      * Reads a collection of field values for the emulated fields
-     * <code>emulatedFields</code>
+     * {@code emulatedFields}
      * 
      * @param emulatedFields
-     *            an <code>EmulatedFieldsForLoading</code>, concrete subclass
-     *            of <code>GetField</code>
+     *            an {@code EmulatedFieldsForLoading}, concrete subclass
+     *            of {@code GetField}
      * 
      * @throws IOException
      *             If an IO exception happened when reading the field values.
@@ -1072,16 +1172,16 @@
 
     /**
      * Reads a collection of field values for the class descriptor
-     * <code>classDesc</code> (an <code>ObjectStreamClass</code>). The
-     * values will be used to set instance fields in object <code>obj</code>.
+     * {@code classDesc} (an {@code ObjectStreamClass}). The
+     * values will be used to set instance fields in object {@code obj}.
      * This is the default mechanism, when emulated fields (an
-     * <code>GetField</code>) are not used. Actual values to load are stored
-     * directly into the object <code>obj</code>.
+     * {@code GetField}) are not used. Actual values to load are stored
+     * directly into the object {@code obj}.
      * 
      * @param obj
      *            Instance in which the fields will be set.
      * @param classDesc
-     *            A class descriptor (an <code>ObjectStreamClass</code>)
+     *            A class descriptor (an {@code ObjectStreamClass})
      *            defining which fields should be loaded.
      * 
      * @throws IOException
@@ -1213,47 +1313,52 @@
     }
 
     /**
-     * Reads and returns primitive data of type float read from the receiver
-     * 
-     * @return A float saved as primitive data using
-     *         <code>ObjectOutputStream.writeFloat()</code>
+     * Reads a float (32 bit) from the source stream.
      * 
+     * @return the float value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public float readFloat() throws IOException {
         return primitiveTypes.readFloat();
     }
 
     /**
-     * Reads bytes from the receiver into the byte array <code>buffer</code>.
-     * This method will block until <code>buffer.length</code> number of bytes
-     * have been read.
+     * Reads bytes from the source stream into the byte array {@code buffer}.
+     * This method will block until {@code buffer.length} bytes have been read.
      * 
      * @param buffer
-     *            the buffer to read bytes into
-     * 
+     *            the array in which to store the bytes read.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             if a problem occurs reading from this stream.
+     *             if an error occurs while reading from the source stream.
      */
     public void readFully(byte[] buffer) throws IOException {
         primitiveTypes.readFully(buffer);
     }
 
     /**
-     * Reads bytes from the receiver into the byte array <code>buffer</code>.
-     * This method will block until <code>length</code> number of bytes have
-     * been read.
+     * Reads bytes from the source stream into the byte array {@code buffer}.
+     * This method will block until {@code length} number of bytes have been
+     * read.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the byte array in which to store the bytes read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read bytes.
+     *            the initial position in {@code buffer} to store the bytes
+     *            read from the source stream.
      * @param length
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             if a problem occurs reading from this stream.
+     *             if an error occurs while reading from the source stream.
      */
     public void readFully(byte[] buffer, int offset, int length)
             throws IOException {
@@ -1262,17 +1367,17 @@
 
     /**
      * Walks the hierarchy of classes described by class descriptor
-     * <code>classDesc</code> and reads the field values corresponding to
+     * {@code classDesc} and reads the field values corresponding to
      * fields declared by the corresponding class descriptor. The instance to
-     * store field values into is <code>object</code>. If the class
-     * (corresponding to class descriptor <code>classDesc</code>) defines
-     * private instance method <code>readObject</code> it will be used to load
+     * store field values into is {@code object}. If the class
+     * (corresponding to class descriptor {@code classDesc}) defines
+     * private instance method {@code readObject} it will be used to load
      * field values.
      * 
      * @param object
      *            Instance into which stored field values loaded.
      * @param classDesc
-     *            A class descriptor (an <code>ObjectStreamClass</code>)
+     *            A class descriptor (an {@code ObjectStreamClass})
      *            defining which fields should be loaded.
      * 
      * @throws IOException
@@ -1281,7 +1386,7 @@
      * @throws ClassNotFoundException
      *             If a class for one of the field types could not be found
      * @throws NotActiveException
-     *             If <code>defaultReadObject</code> is called from the wrong
+     *             If {@code defaultReadObject} is called from the wrong
      *             context.
      * 
      * @see #defaultReadObject
@@ -1433,29 +1538,27 @@
     }
 
     /**
-     * Reads and returns primitive data of type int read from the receiver
-     * 
-     * @return an int saved as primitive data using
-     *         <code>ObjectOutputStream.writeInt()</code>
+     * Reads an integer (32 bit) from the source stream.
      * 
+     * @return the integer value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public int readInt() throws IOException {
         return primitiveTypes.readInt();
     }
 
     /**
-     * Reads and returns the next line (primitive data of type String) read from
-     * the receiver
-     * 
-     * @return a String saved as primitive data using
-     *         <code>ObjectOutputStream.writeLine()</code>
+     * Reads the next line from the source stream. Lines are terminated by
+     * {@code '\r'}, {@code '\n'}, {@code "\r\n"} or an {@code EOF}.
      * 
+     * @return the string read from the source stream.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
-     * 
-     * @deprecated Use BufferedReader
+     *             if an error occurs while reading from the source stream.
+     * @deprecated Use {@link BufferedReader}
      */
     @Deprecated
     public String readLine() throws IOException {
@@ -1463,13 +1566,14 @@
     }
 
     /**
-     * Reads and returns primitive data of type long read from the receiver
-     * 
-     * @return a long saved as primitive data using
-     *         <code>ObjectOutputStream.writeLong()</code>
+     * Reads a long (64 bit) from the source stream.
      * 
+     * @return the long value read from the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public long readLong() throws IOException {
         return primitiveTypes.readLong();
@@ -1579,7 +1683,7 @@
      * 
      * @param unshared
      *            read the object unshared
-     * @return The <code>java.lang.Class</code> read from the stream.
+     * @return The {@code java.lang.Class} read from the stream.
      * 
      * @throws IOException
      *             If an IO exception happened when reading the class.
@@ -1691,7 +1795,7 @@
      * 
      * @param unshared
      *            read the object unshared
-     * @return The <code>ObjectStreamClass</code> read from the stream.
+     * @return The {@code ObjectStreamClass} read from the stream.
      * 
      * @throws IOException
      *             If an IO exception happened when reading the class
@@ -1744,7 +1848,7 @@
      * proxy class descriptor has not been read yet (not a cyclic reference).
      * Return the proxy class descriptor read.
      * 
-     * @return The <code>Class</code> read from the stream.
+     * @return The {@code Class} read from the stream.
      * 
      * @throws IOException
      *             If an IO exception happened when reading the class
@@ -1766,16 +1870,13 @@
     }
 
     /**
-     * Reads a new class descriptor from the receiver. Return the class
-     * descriptor read.
-     * 
-     * @return The <code>ObjectStreamClass</code> read from the stream.
+     * Reads a class descriptor from the source stream.
      * 
-     * @throws IOException
-     *             If an IO exception happened when reading the class
-     *             descriptor.
+     * @return the class descriptor read from the source stream.
      * @throws ClassNotFoundException
-     *             If a class for one of the objects could not be found
+     *             if a class for one of the objects cannot be found.
+     * @throws IOException
+     *             if an error occurs while reading from the source stream.
      */
     protected ObjectStreamClass readClassDescriptor() throws IOException,
             ClassNotFoundException {
@@ -1803,16 +1904,18 @@
     }
 
     /**
-     * Retrieves the proxy class corresponding to the interface names.
+     * Creates the proxy class that implements the interfaces specified in
+     * {@code interfaceNames}.
      * 
      * @param interfaceNames
-     *            The interfaces used to create the proxy class
-     * @return A proxy class
-     * 
-     * @throws IOException
-     *             If any IO problem occurred when trying to load the class.
+     *            the interfaces used to create the proxy class.
+     * @return the proxy class.
      * @throws ClassNotFoundException
-     *             If the proxy class cannot be created
+     *             if the proxy class or any of the specified interfaces cannot
+     *             be created.
+     * @throws IOException
+     *             if an error occurs while reading from the source stream.
+     * @see ObjectOutputStream#annotateProxyClass(Class)
      */
     protected Class<?> resolveProxyClass(String[] interfaceNames)
             throws IOException, ClassNotFoundException {
@@ -2045,13 +2148,12 @@
     }
 
     /**
-     * Read a new String in UTF format from the receiver. Return the string
-     * read.
+     * Read a string encoded in {@link DataInput modified UTF-8} from the
+     * receiver. Return the string read.
      * 
      * @param unshared
      *            read the object unshared
      * @return the string just read.
-     * 
      * @throws IOException
      *             If an IO exception happened when reading the String.
      */
@@ -2088,18 +2190,16 @@
     }
 
     /**
-     * Read the next object from the receiver's underlying stream.
-     * 
-     * @return the new object read.
+     * Reads the next object from the source stream.
      * 
-     * @throws IOException
-     *             If an IO exception happened when reading the object
+     * @return the object read from the source stream.
      * @throws ClassNotFoundException
-     *             If the class of one of the objects in the object graph could
-     *             not be found
+     *             if the class of one of the objects in the object graph cannot
+     *             be found.
+     * @throws IOException
+     *             if an error occurs while reading from the source stream.
      * @throws OptionalDataException
-     *             If primitive data types were found instead of an object.
-     * 
+     *             if primitive data types were found instead of an object.
      * @see ObjectOutputStream#writeObject(Object)
      */
     public final Object readObject() throws OptionalDataException,
@@ -2108,16 +2208,14 @@
     }
 
     /**
-     * Read the next unshared object from the receiver's underlying stream.
+     * Reads the next unshared object from the source stream.
      * 
      * @return the new object read.
-     * 
-     * @throws IOException
-     *             If an IO exception happened when reading the object
      * @throws ClassNotFoundException
-     *             If the class of one of the objects in the object graph could
-     *             not be found
-     * 
+     *             if the class of one of the objects in the object graph cannot
+     *             be found.
+     * @throws IOException
+     *             if an error occurs while reading from the source stream.
      * @see ObjectOutputStream#writeUnshared
      */
     public Object readUnshared() throws IOException, ClassNotFoundException {
@@ -2185,18 +2283,16 @@
 
     /**
      * Method to be overriden by subclasses to read the next object from the
-     * receiver's underlying stream.
-     * 
-     * @return the new object read.
+     * source stream.
      * 
-     * @throws IOException
-     *             If an IO exception happened when reading the object
+     * @return the object read from the source stream.
      * @throws ClassNotFoundException
-     *             If the class of one of the objects in the object graph could
-     *             not be found
+     *             if the class of one of the objects in the object graph cannot
+     *             be found.
+     * @throws IOException
+     *             if an error occurs while reading from the source stream.
      * @throws OptionalDataException
-     *             If primitive data types were found instead of an object.
-     * 
+     *             if primitive data types were found instead of an object.
      * @see ObjectOutputStream#writeObjectOverride
      */
     protected Object readObjectOverride() throws OptionalDataException,
@@ -2209,26 +2305,24 @@
     }
 
     /**
-     * Reads and returns primitive data of type short from the receiver
-     * 
-     * @return a short saved as primitive data using
-     *         <code>ObjectOutputStream.writeShort()</code>
+     * Reads a short (16 bit) from the source stream.
      * 
+     * @return the short value read from the source stream.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public short readShort() throws IOException {
         return primitiveTypes.readShort();
     }
 
     /**
-     * Reads and validates the ObjectInputStream header from the receiver
+     * Reads and validates the ObjectInputStream header from the source stream.
      * 
      * @throws IOException
-     *             If an IO exception happened when reading the stream header.
+     *             if an error occurs while reading from the source stream.
      * @throws StreamCorruptedException
-     *             If the underlying stream does not contain serialized objects
-     *             that can be read.
+     *             if the source stream does not contain readable serialized
+     *             objects.
      */
     protected void readStreamHeader() throws IOException,
             StreamCorruptedException {
@@ -2240,49 +2334,53 @@
     }
 
     /**
-     * Reads and returns primitive data of type byte (unsigned) from the
-     * receiver
-     * 
-     * @return a byte saved as primitive data using
-     *         <code>ObjectOutputStream.writeUnsignedByte()</code>
+     * Reads an unsigned byte (8 bit) from the source stream.
      * 
+     * @return the unsigned byte value read from the source stream packaged in
+     *         an integer.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public int readUnsignedByte() throws IOException {
         return primitiveTypes.readUnsignedByte();
     }
 
     /**
-     * Reads and returns primitive data of type short (unsigned) from the
-     * receiver
-     * 
-     * @return a short saved as primitive data using
-     *         <code>ObjectOutputStream.writeUnsignedShort()</code>
+     * Reads an unsigned short (16 bit) from the source stream.
      * 
+     * @return the unsigned short value read from the source stream packaged in
+     *         an integer.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public int readUnsignedShort() throws IOException {
         return primitiveTypes.readUnsignedShort();
     }
 
     /**
-     * Reads and returns primitive data of type String read in UTF format from
-     * the receiver
-     * 
-     * @return a String saved as primitive data using
-     *         <code>ObjectOutputStream.writeUTF()</code>
+     * Reads a string encoded in {@link DataInput modified UTF-8} from the
+     * source stream.
      * 
+     * @return the string encoded in {@link DataInput modified UTF-8} read from
+     *         the source stream.
+     * @throws EOFException
+     *             if the end of the input is reached before the read
+     *             request can be satisfied.
      * @throws IOException
-     *             If an IO exception happened when reading the primitive data.
+     *             if an error occurs while reading from the source stream.
      */
     public String readUTF() throws IOException {
         return primitiveTypes.readUTF();
     }
 
     /**
-     * Return the object previously read tagged with handle <code>handle</code>.
+     * Return the object previously read tagged with handle {@code handle}.
      * 
      * @param handle
      *            The handle that this object was assigned when it was read.
@@ -2303,8 +2401,8 @@
     }
 
     /**
-     * Assume object <code>obj</code> has been read, and assign a handle to
-     * it, <code>handle</code>.
+     * Assume object {@code obj} has been read, and assign a handle to
+     * it, {@code handle}.
      * 
      * @param obj
      *            Non-null object being loaded.
@@ -2320,19 +2418,24 @@
     }
 
     /**
-     * Register object validator <code>object</code> to be executed to perform
-     * validation of objects loaded from the receiver. Validations will be run
-     * in order of decreasing priority, defined by <code>priority</code>.
+     * Registers a callback for post-deserialization validation of objects. It
+     * allows to perform additional consistency checks before the {@code
+     * readObject()} method of this class returns its result to the caller. This
+     * method can only be called from within the {@code readObject()} method of
+     * a class that implements "special" deserialization rules. It can be called
+     * multiple times. Validation callbacks are then done in order of decreasing
+     * priority, defined by {@code priority}.
      * 
      * @param object
-     *            An ObjectInputValidation to validate objects loaded.
+     *            an object that can validate itself by receiving a callback.
      * @param priority
-     *            validator priority
-     * 
-     * @throws NotActiveException
-     *             If this method is not called from <code>readObject()</code>
+     *            the validator's priority.
      * @throws InvalidObjectException
-     *             If <code>object</code> is null.
+     *             if {@code object} is {@code null}.
+     * @throws NotActiveException
+     *             if this stream is currently not reading objects. In that
+     *             case, calling this method is not allowed.
+     * @see ObjectInputValidation#validateObject()
      */
     public synchronized void registerValidation(ObjectInputValidation object,
             int priority) throws NotActiveException, InvalidObjectException {
@@ -2398,17 +2501,17 @@
     }
 
     /**
-     * Loads the Java class corresponding to the class descriptor
-     * <code>osClass</code>(ObjectStreamClass) just read from the receiver.
+     * Loads the Java class corresponding to the class descriptor {@code
+     * osClass} that has just been read from the source stream.
      * 
      * @param osClass
-     *            An ObjectStreamClass read from the receiver.
-     * @return a Class corresponding to the descriptor loaded.
-     * 
-     * @throws IOException
-     *             If any IO problem occurred when trying to load the class.
+     *            an ObjectStreamClass read from the source stream.
+     * @return a Class corresponding to the descriptor {@code osClass}.
      * @throws ClassNotFoundException
-     *             If the corresponding class cannot be found.
+     *             if the class for an object cannot be found.
+     * @throws IOException
+     *             if an I/O error occurs while creating the class.
+     * @see ObjectOutputStream#annotateClass(Class)
      */
     protected Class<?> resolveClass(ObjectStreamClass osClass)
             throws IOException, ClassNotFoundException {
@@ -2432,17 +2535,17 @@
     }
 
     /**
-     * If <code>enableResolveObject()</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 enableResolveObject(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 #enableResolveObject
      * @see ObjectOutputStream#enableReplaceObject
      * @see ObjectOutputStream#replaceObject
@@ -2453,17 +2556,17 @@
     }
 
     /**
-     * Skips <code>length</code> bytes of primitive data from the receiver. It
-     * should not be used to skip bytes at any arbitrary position; just when
-     * reading primitive data types (ints, chars, etc).
-     * 
-     * 
+     * Skips {@code length} bytes on the source stream. This method should not
+     * be used to skip bytes at any arbitrary position, just when reading
+     * primitive data types (int, char etc).
+     *
      * @param length
-     *            How many bytes to skip
-     * @return number of bytes skipped
-     * 
+     *            the number of bytes to skip.
+     * @return the number of bytes actually skipped.
      * @throws IOException
-     *             If any IO problem occurred when trying to skip the bytes.
+     *             if an error occurs while skipping bytes on the source stream.
+     * @throws NullPointerException
+     *             if the source stream is {@code null}.
      */
     public int skipBytes(int length) throws IOException {
         // To be used with available. Ok to call if reading primitive buffer
@@ -2484,7 +2587,7 @@
     }
 
     /**
-     * Verify if the SUID & the base name for descriptor 
+     * Verify if the SUID & the base name for descriptor
      * <code>loadedStreamClass</code>matches
      * the SUID & the base name of the corresponding loaded class and
      * init private fields.

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputValidation.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputValidation.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputValidation.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputValidation.java Fri May  1 08:08:59 2009
@@ -18,19 +18,18 @@
 package java.io;
 
 /**
- * Objects to perform validations on other objects read with serialization
- * should implement this interface. An object's <code>readObject()</code> can
- * call <code>ObjectInputStream.registerValidation()</code> passing an object
- * that implements ObjectInputValidation.
+ * A callback interface for post-deserialization checks on objects. Allows, for
+ * example, the validation of a whole graph of objects after all of them have
+ * been loaded.
  * 
- * @see ObjectInputStream
+ * @see ObjectInputStream#registerValidation(ObjectInputValidation, int)
  */
 public interface ObjectInputValidation {
     /**
-     * Validates an object read with serialization.
+     * Validates this object.
      * 
      * @throws InvalidObjectException
-     *             if the receiver fails to validate the object read
+     *             if this object fails to validate itself.
      */
     public void validateObject() throws InvalidObjectException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutput.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutput.java Fri May  1 08:08:59 2009
@@ -18,79 +18,77 @@
 package java.io;
 
 /**
- * Streams to be used with serialization to write objects must implement this
- * interface. ObjectOutputStream is one example.
+ * Defines an interface for classes that allow reading serialized objects.
  * 
  * @see ObjectOutputStream
  * @see ObjectInput
  */
 public interface ObjectOutput extends DataOutput {
     /**
-     * Close this ObjectOutput. Concrete implementations of this class should
-     * free any resources during close.
+     * Closes the target stream. Implementations of this method should free any
+     * resources used by the stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this ObjectOutput.
+     *             if an error occurs while closing the target stream.
      */
     public void close() throws IOException;
 
     /**
-     * Flush this ObjectOutput. Concrete implementations of this class should
-     * ensure any pending writes are written out when this method is envoked.
+     * Flushes the target stream. Implementations of this method should ensure
+     * that any pending writes are written out to the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this ObjectOutput.
+     *             if an error occurs while flushing the target stream.
      */
     public void flush() throws IOException;
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to
-     * this ObjectOutput.
+     * 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
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this ObjectOutput.
+     *            the buffer to write.
+     * @throws IOException
+     *             if an error occurs while writing to the target stream.
      */
     public void write(byte[] buffer) throws IOException;
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from this byte array
-     * <code>buffer</code> starting at offset <code>index</code> to this
-     * ObjectOutput.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * position {@code offset} 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 count
-     *            number of bytes in buffer to write
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this ObjectOutput.
+     *            the number of bytes from {@code buffer} to write to the target
+     *            stream.
+     * @throws IOException
+     *             if an error occurs while writing to the target stream.
      */
     public void write(byte[] buffer, int offset, int count) throws IOException;
 
     /**
-     * Writes the specified int <code>value</code> to this ObjectOutput.
+     * 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 int to be written
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this ObjectOutput.
+     *            the byte to write.
+     * @throws IOException
+     *             if an error occurs while writing to the target stream.
      */
     public void write(int value) throws IOException;
 
     /**
-     * Writes the specified object <code>obj</code> to this ObjectOutput.
+     * Writes the specified object {@code obj} to the target stream.
      * 
      * @param obj
-     *            the object to be written
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this ObjectOutput.
+     *            the object to write.
+     * @throws IOException
+     *             if an error occurs while writing to the target stream.
      */
     public void writeObject(Object obj) throws IOException;
 }



Mime
View raw message