Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 20335 invoked from network); 1 May 2009 08:09:45 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 1 May 2009 08:09:45 -0000 Received: (qmail 63684 invoked by uid 500); 1 May 2009 08:09:45 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 63630 invoked by uid 500); 1 May 2009 08:09:44 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 63621 invoked by uid 99); 1 May 2009 08:09:44 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:09:44 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:09:26 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 5EB012388CE3; Fri, 1 May 2009 08:09:04 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090501080904.5EB012388CE3@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 in. - * 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 in. - * The buffer size is specified by the parameter size 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 - * readLimit indicates how many characters can be read before - * a mark is invalidated. Sending reset() will reposition the reader back to - * the marked position provided readLimit has not been - * surpassed. The lineNumber associated with this marked position will also - * be saved and restored when reset() is sent provided - * readLimit 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. + *

* 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 count chars from this LineNumberReader and - * stores them in char array buffer starting at offset - * offset. 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. + *

+ * 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 buffer 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 buffer. - * @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 String representing the next line of text - * available in this LineNumberReader. A line is represented by 0 or more - * characters followed by '\n', '\r', - * "\n\r" or end of stream. The String 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 - * readlimit has been passed or no mark 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 - * lineNumber. 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 count number of chars in this LineNumberReader. - * Subsequent read()'s will not return these chars unless - * reset() is used. This implementation skips - * count 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: *

    - *
  • ObjectInputStream.defaultReadObject()
    • - *
  • ObjectInputStream.registerValidation()
    • - *
  • ObjectOutputStream.defaultWriteObject()
    • + *
  • {@link ObjectInputStream#defaultReadObject()}
    • + *
  • {@link ObjectInputStream#registerValidation(ObjectInputValidation, int)}
    • + *
  • {@link ObjectOutputStream#defaultWriteObject()}
    • *
- * - * @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 ObjectInput and stores them in byte - * array buffer. 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 -1 if encountered end - * of ObjectInput. - * + * 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 ObjectInput 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 count bytes from the ObjectInput and stores - * them in byte array buffer starting at offset - * count. 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 buffer 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 buffer. - * @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 toSkip number of bytes in this ObjectInput. - * Subsequent read()'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 true if the default value is set, - * false 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 input. - * 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 true if the two classes belong to the same - * package, false 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 Integer 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 length bytes from the receiver and stores - * them in byte array buffer starting at offset - * offset. 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 buffer 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 buffer. - * @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 DataOutputStream. + * 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 DataOutputStream. + * 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 - * ObjectOutputStream.writeBoolean() + * 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 - * ObjectOutputStream.writeByte() + * 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 - * ObjectOutputStream.writeChar() + * 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 ObjectStreamClass) 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 - * tc. + * {@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 - * tc. 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 - * ObjectOutputStream.writeDouble() + * 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 cDesc (an ObjectStreamClass) + * class descriptor {@code cDesc} (an {@code ObjectStreamClass}) * * @param cDesc - * The class descriptor (an ObjectStreamClass) + * 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 getField 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 - * emulatedFields + * {@code emulatedFields} * * @param emulatedFields - * an EmulatedFieldsForLoading, concrete subclass - * of GetField + * 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 - * classDesc (an ObjectStreamClass). The - * values will be used to set instance fields in object obj. + * {@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 - * GetField) are not used. Actual values to load are stored - * directly into the object obj. + * {@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 ObjectStreamClass) + * 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 - * ObjectOutputStream.writeFloat() + * 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 buffer. - * This method will block until buffer.length 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 buffer. - * This method will block until length 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 buffer 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 buffer. - * + * 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 - * classDesc 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 object. If the class - * (corresponding to class descriptor classDesc) defines - * private instance method readObject 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 ObjectStreamClass) + * 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 defaultReadObject 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 - * ObjectOutputStream.writeInt() + * 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 - * ObjectOutputStream.writeLine() + * 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 - * ObjectOutputStream.writeLong() + * 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 java.lang.Class 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 ObjectStreamClass 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 Class 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 ObjectStreamClass 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 - * ObjectOutputStream.writeShort() + * 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 - * ObjectOutputStream.writeUnsignedByte() + * 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 - * ObjectOutputStream.writeUnsignedShort() + * 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 - * ObjectOutputStream.writeUTF() + * 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 handle. + * 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 obj has been read, and assign a handle to - * it, handle. + * 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 object to be executed to perform - * validation of objects loaded from the receiver. Validations will be run - * in order of decreasing priority, defined by priority. + * 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 readObject() + * the validator's priority. * @throws InvalidObjectException - * If object 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 - * osClass(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 enableResolveObject() was activated, computes the - * replacement object for the original object object and - * returns the replacement. Otherwise returns object. + * 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 object - * + * 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 length 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 * loadedStreamClassmatches * 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 readObject() can - * call ObjectInputStream.registerValidation() 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 buffer 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 count bytes from this byte array - * buffer starting at offset index 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 value 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 obj 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; }