harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [9/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/RandomAccessFile.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/RandomAccessFile.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/RandomAccessFile.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/RandomAccessFile.java Fri May  1 08:08:59 2009
@@ -27,10 +27,12 @@
 import org.apache.harmony.nio.FileChannelFactory;
 
 /**
- * RandomAccessFile is a class which allows positioning of the next read
- * anywhere in the file. This is useful for reading specific locations of files
- * or following links within a file. Most input classes only support forward
- * skipping.
+ * Allows reading from and writing to a file in a random-access manner. This is
+ * different from the uni-directional sequential access that a
+ * {@link FileInputStream} or {@link FileOutputStream} provides. If the file is
+ * opened in read/write mode, write operations are available as well. The
+ * position of the next read or write operation can be moved forwards and
+ * backwards after every operation.
  */
 public class RandomAccessFile implements DataInput, DataOutput, Closeable {
     /**
@@ -54,20 +56,48 @@
     private Object repositionLock = new RepositionLock();
 
     /**
-     * Constructs a new RandomAccessFile on the File <code>file</code> and
-     * opens it according to the access String in <code>mode</code>. The
-     * access mode may be one of <code>"r"</code> for read access only, or
-     * <code>"rw"</code> for read/write access.
-     * 
+     * Constructs a new {@code RandomAccessFile} based on {@code file} and opens
+     * it according to the access string in {@code mode}.
+     * <p><a id="accessmode"/>
+     * {@code mode} may have one of following values:
+     * <table border="0">
+     * <tr>
+     * <td>{@code "r"}</td>
+     * <td>The file is opened in read-only mode. An {@code IOException} is
+     * thrown if any of the {@code write} methods is called.</td>
+     * </tr>
+     * <tr>
+     * <td>{@code "rw"}</td>
+     * <td>The file is opened for reading and writing. If the file does not
+     * exist, it will be created.</td>
+     * </tr>
+     * <tr>
+     * <td>{@code "rws"}</td>
+     * <td>The file is opened for reading and writing. Every change of the
+     * file's content or metadata must be written synchronously to the target
+     * device.</td>
+     * </tr>
+     * <tr>
+     * <td>{@code "rwd"}</td>
+     * <td>The file is opened for reading and writing. Every change of the
+     * file's content must be written synchronously to the target device.</td>
+     * </tr>
+     * </table>
+     *
      * @param file
-     *            the File to open.
+     *            the file to open.
      * @param mode
-     *            "r" for read only, or "rw" for read/write.
-     * 
+     *            the file access <a href="#accessmode">mode</a>, either {@code
+     *            "r"}, {@code "rw"}, {@code "rws"} or {@code "rwd"}.
      * @throws FileNotFoundException
-     *             If the <code>mode</code> is incorrect or the File cannot be
-     *             opened in the requested <code>mode</code>.
-     * 
+     *             if the file cannot be opened or created according to {@code
+     *             mode}.
+     * @throws IllegalArgumentException
+     *             if {@code mode} is not {@code "r"}, {@code "rw"}, {@code
+     *             "rws"} or {@code "rwd"}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies
+     *             access request according to {@code mode}.
      * @see java.lang.SecurityManager#checkRead(FileDescriptor)
      * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
      */
@@ -121,22 +151,25 @@
     }
 
     /**
-     * Constructs a new RandomAccessFile on the file named <code>fileName</code>
-     * and opens it according to the access String in <code>mode</code>. The
-     * file may be absolute or relative to the System property
-     * <code>"user.dir"</code>. The access mode may be one of
-     * <code>"r"</code> for read access only, or <code>"rw"</code> for
-     * read/write access.
+     * Constructs a new {@code RandomAccessFile} based on the file named {@code
+     * fileName} and opens it according to the access string in {@code mode}.
+     * The file path may be specified absolutely or relative to the system
+     * property {@code "user.dir"}.
      * 
      * @param fileName
-     *            the filename of the file to open.
+     *            the name of the file to open.
      * @param mode
-     *            "r" for read only, or "rw" for read/write.
-     * 
+     *            the file access <a href="#accessmode">mode</a>, either {@code
+     *            "r"}, {@code "rw"}, {@code "rws"} or {@code "rwd"}.
      * @throws FileNotFoundException
-     *             If the <code>mode</code> is incorrect or the file cannot be
-     *             opened in the requested <code>mode</code>.
-     * 
+     *             if the file cannot be opened or created according to {@code
+     *             mode}.
+     * @throws IllegalArgumentException
+     *             if {@code mode} is not {@code "r"}, {@code "rw"}, {@code
+     *             "rws"} or {@code "rwd"}.
+     * @throws SecurityException
+     *             if a {@code SecurityManager} is installed and it denies
+     *             access request according to {@code mode}.
      * @see java.lang.SecurityManager#checkRead(FileDescriptor)
      * @see java.lang.SecurityManager#checkWrite(FileDescriptor)
      */
@@ -146,10 +179,10 @@
     }
 
     /**
-     * Close this RandomAccessFile.
+     * Closes this file.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this RandomAccessFile.
+     *             if an error occurs while closing this file.
      */
     public void close() throws IOException {
         synchronized (channel) {
@@ -166,43 +199,41 @@
     }
 
     /**
-     * Answers the FileChannel equivalent to this stream.
+     * Gets this file's {@link FileChannel} object.
      * <p>
-     * The file channel is write-only and has an initial position within the
-     * file that is the same as the current position of this FileOutputStream
-     * within the file. All changes made to the underlying file descriptor state
-     * via the channel are visible by the output stream and vice versa.
-     * </p>
+     * The file channel's {@link FileChannel#position() position} is the same
+     * as this file's file pointer offset (see {@link #getFilePointer()}). Any
+     * changes made to this file's file pointer offset are also visible in the
+     * file channel's position and vice versa.
      * 
-     * @return the file channel representation for this FileOutputStream.
+     * @return this file's file channel instance.
      */
     public final synchronized FileChannel getChannel() {
         return channel;
     }
 
     /**
-     * Answers the FileDescriptor representing the operating system resource for
-     * this RandomAccessFile.
-     * 
-     * @return the FileDescriptor for this RandomAccessFile.
+     * Gets this file's {@link FileDescriptor}. This represents the operating
+     * system resource for this random access file.
      * 
+     * @return this file's file descriptor object.
      * @throws IOException
-     *             If an error occurs attempting to get the FileDescriptor of
-     *             this RandomAccessFile.
+     *             if an error occurs while getting the file descriptor of this
+     *             file.
      */
     public final FileDescriptor getFD() throws IOException {
         return fd;
     }
 
     /**
-     * Answers the current position within this RandomAccessFile. All reads and
+     * Gets the current position within this file. All reads and
      * writes take place at the current file pointer position.
      * 
-     * @return the current file pointer position.
+     * @return the current offset in bytes from the beginning of the file.
      * 
      * @throws IOException
-     *             If an error occurs attempting to get the file pointer
-     *             position of this RandomAccessFile.
+     *             if an error occurs while getting the file pointer of this
+     *             file.
      */
     public long getFilePointer() throws IOException {
         openCheck();
@@ -223,13 +254,11 @@
     }
 
     /**
-     * Answers the current length of this RandomAccessFile in bytes.
-     * 
-     * @return the current file length in bytes.
+     * Returns the length of this file in bytes.
      * 
+     * @return the file's length in bytes.
      * @throws IOException
-     *             If an error occurs attempting to get the file length of this
-     *             RandomAccessFile.
+     *             if this file is closed or some other I/O error occurs.
      */
     public long length() throws IOException {
         openCheck();
@@ -245,19 +274,14 @@
     }
 
     /**
-     * Reads a single byte from this RandomAccessFile and returns the result as
-     * an int. The low-order byte is returned or -1 of the end of file was
-     * encountered.
-     * 
-     * @return the byte read or -1 if end of file.
+     * Reads a single byte from the current position in this file and returns it
+     * as an integer in the range from 0 to 255. Returns -1 if the end of the
+     * file has been reached. Blocks until one byte has been read, the end of
+     * the file is detected or an exception is thrown.
      * 
+     * @return the byte read or -1 if the end of the file has been reached.
      * @throws IOException
-     *             If an error occurs attempting to read from this
-     *             RandomAccessFile.
-     * 
-     * @see #write(byte[])
-     * @see #write(byte[], int, int)
-     * @see #write(int)
+     *             if this file is closed or another I/O error occurs.
      */
     public int read() throws IOException {
         openCheck();
@@ -269,46 +293,42 @@
     }
 
     /**
-     * Reads bytes from this RandomAccessFile into the byte array
-     * <code>buffer</code>. The number of bytes actually read is returned.
+     * Reads bytes from the current position in this file and stores them in the
+     * byte array {@code buffer}. The maximum number of bytes read corresponds
+     * to the size of {@code buffer}. Blocks until at least one byte has been
+     * read.
      * 
      * @param buffer
-     *            the buffer to read bytes into
-     * @return the number of bytes actually read or -1 if end of file.
-     * 
+     *            the byte array in which to store the bytes read.
+     * @return the number of bytes actually read or -1 if the end of the file
+     *         has been reached.
      * @throws IOException
-     *             If an error occurs attempting to read from this
-     *             RandomAccessFile.
-     * 
-     * @see #write(byte[])
-     * @see #write(byte[], int, int)
-     * @see #write(int)
+     *             if this file is closed or another I/O error occurs.
      */
     public int read(byte[] buffer) throws IOException {
         return read(buffer, 0, buffer.length);
     }
 
     /**
-     * Reads at most <code>count</code> bytes from this RandomAccessFile and
-     * stores them in byte array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of file was encountered.
+     * Reads at most {@code count} bytes from the current position in this file
+     * and stores them in the byte array {@code buffer} starting at {@code
+     * offset}. Blocks until {@code count} bytes have been read, the end of the
+     * file is reached 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 from this file.
      * @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 file.
      * @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 file.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes actually read or -1 if the end of the stream
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the size of {@code buffer}.
      * @throws IOException
-     *             If an error occurs attempting to read from this
-     *             RandomAccessFile.
-     * 
-     * @see #write(byte[])
-     * @see #write(byte[], int, int)
-     * @see #write(int)
+     *             if this file is closed or another I/O error occurs.
      */
     public int read(byte[] buffer, int offset, int count) throws IOException {
         // have to have four comparisions to not miss integer overflow cases
@@ -325,14 +345,16 @@
     }
 
     /**
-     * Reads a boolean from this stream.
-     * 
-     * @return boolean the next boolean value from the source stream.
-     * 
+     * Reads a boolean from the current position in this file. Blocks until one
+     * byte has been read, the end of the file is reached or an exception is
+     * thrown.
+     * 
+     * @return the next boolean value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeBoolean(boolean)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeBoolean(boolean)
      */
     public final boolean readBoolean() throws IOException {
         int temp = this.read();
@@ -343,14 +365,16 @@
     }
 
     /**
-     * Reads an 8-bit byte value from this stream.
-     * 
-     * @return byte the next byte value from the source stream.
-     * 
+     * Reads an 8-bit byte from the current position in this file. Blocks until
+     * one byte has been read, the end of the file is reached or an exception is
+     * thrown.
+     * 
+     * @return the next signed 8-bit byte value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeByte(int)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeBoolean(boolean)
      */
     public final byte readByte() throws IOException {
         int temp = this.read();
@@ -361,14 +385,16 @@
     }
 
     /**
-     * Reads a 16-bit character value from this stream.
-     * 
-     * @return char the next <code>char</code> value from the source stream.
-     * 
+     * Reads a 16-bit character from the current position in this file. Blocks until
+     * two bytes have been read, the end of the file is reached or an exception is
+     * thrown.
+     * 
+     * @return the next char value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeChar(int)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeChar(int)
      */
     public final char readChar() throws IOException {
         byte[] buffer = new byte[2];
@@ -379,69 +405,76 @@
     }
 
     /**
-     * Reads a 64-bit <code>double</code> value from this stream.
-     * 
-     * @return double the next <code>double</code> value from the source
-     *         stream.
-     * 
+     * Reads a 64-bit double from the current position in this file. Blocks
+     * until eight bytes have been read, the end of the file is reached or an
+     * exception is thrown.
+     * 
+     * @return the next double value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeDouble(double)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeDouble(double)
      */
     public final double readDouble() throws IOException {
         return Double.longBitsToDouble(readLong());
     }
 
     /**
-     * Reads a 32-bit <code>float</code> value from this stream.
-     * 
-     * @return float the next <code>float</code> value from the source stream.
-     * 
+     * Reads a 32-bit float from the current position in this file. Blocks
+     * until four bytes have been read, the end of the file is reached or an
+     * exception is thrown.
+     * 
+     * @return the next float value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeFloat(float)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeFloat(float)
      */
     public final float readFloat() throws IOException {
         return Float.intBitsToFloat(readInt());
     }
 
     /**
-     * Reads bytes from this stream 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 this file into {@code buffer}. Blocks until {@code
+     * buffer.length} number of bytes have been read, the end of the file is
+     * reached or an exception is thrown.
      * 
      * @param buffer
-     *            the buffer to read bytes into
-     * 
-     * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#write(byte[])
-     * @see DataOutput#write(byte[], int, int)
+     *            the buffer to read bytes into.
+     * @throws EOFException
+     *             if the end of this file is detected.
+     * @throws IOException
+     *             if this file is closed or another I/O error occurs.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     public final void readFully(byte[] buffer) throws IOException {
         readFully(buffer, 0, buffer.length);
     }
 
     /**
-     * Read bytes from this stream and stores them in byte array
-     * <code>buffer</code> starting at offset <code>offset</code>. This
-     * method blocks until <code>count</code> number of bytes have been read.
+     * Read bytes from this file into {@code buffer} starting at offset {@code
+     * offset}. This method blocks until {@code count} number of bytes have been
+     * read.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the buffer to read bytes into.
      * @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 file.
      * @param count
-     *            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 this file is detected.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the length of {@code buffer}.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#write(byte[])
-     * @see DataOutput#write(byte[], int, int)
+     *             if this file is closed or another I/O error occurs.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     public final void readFully(byte[] buffer, int offset, int count)
             throws IOException {
@@ -464,14 +497,16 @@
     }
 
     /**
-     * Reads a 32-bit integer value from this stream.
-     * 
-     * @return int the next <code>int</code> value from the source stream.
-     * 
+     * Reads a 32-bit integer from the current position in this file. Blocks
+     * until four bytes have been read, the end of the file is reached or an
+     * exception is thrown.
+     * 
+     * @return the next int value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeInt(int)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeInt(int)
      */
     public final int readInt() throws IOException {
         byte[] buffer = new byte[4];
@@ -483,18 +518,18 @@
     }
 
     /**
-     * Answers a <code>String</code> representing the next line of text
-     * available in this BufferedReader. 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.
-     * 
+     * Reads a line of text form the current position in this file. A line is
+     * represented by zero or more characters followed by {@code '\n'}, {@code
+     * '\r'}, {@code "\r\n"} or the end of file marker. The string does not
+     * include the line terminating sequence.
+     * <p>
+     * Blocks until a line terminating sequence has been read, the end of the
+     * file is reached or an exception is thrown.
+     *
+     * @return the contents of the line or {@code null} if no characters have
+     *         been read before the end of the file has been reached.
      * @throws IOException
-     *             If the BufferedReader is already closed or some other IO
-     *             error occurs.
+     *             if this file is closed or another I/O error occurs.
      */
     public final String readLine() throws IOException {
         StringBuilder line = new StringBuilder(80); // Typical line length
@@ -527,14 +562,16 @@
     }
 
     /**
-     * Reads a 64-bit <code>long</code> value from this stream.
-     * 
-     * @return long the next <code>long</code> value from the source stream.
-     * 
+     * Reads a 64-bit long from the current position in this file. Blocks until
+     * eight bytes have been read, the end of the file is reached or an
+     * exception is thrown.
+     * 
+     * @return the next long value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeLong(long)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeLong(long)
      */
     public final long readLong() throws IOException {
         byte[] buffer = new byte[8];
@@ -550,14 +587,16 @@
     }
 
     /**
-     * Reads a 16-bit <code>short</code> value from this stream.
-     * 
-     * @return short the next <code>short</code> value from the source stream.
-     * 
+     * Reads a 16-bit short from the current position in this file. Blocks until
+     * two bytes have been read, the end of the file is reached or an exception
+     * is thrown.
+     * 
+     * @return the next short value from this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeShort(int)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeShort(int)
      */
     public final short readShort() throws IOException {
         byte[] buffer = new byte[2];
@@ -568,15 +607,16 @@
     }
 
     /**
-     * Reads an unsigned 8-bit <code>byte</code> value from this stream and
-     * returns it as an int.
-     * 
-     * @return int the next unsigned byte value from the source stream.
-     * 
+     * Reads an unsigned 8-bit byte from the current position in this file and
+     * returns it as an integer. Blocks until one byte has been read, the end of
+     * the file is reached or an exception is thrown.
+     * 
+     * @return the next unsigned byte value from this file as an int.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeByte(int)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeByte(int)
      */
     public final int readUnsignedByte() throws IOException {
         int temp = this.read();
@@ -587,16 +627,16 @@
     }
 
     /**
-     * Reads a 16-bit unsigned <code>short</code> value from this stream and
-     * returns it as an int.
-     * 
-     * @return int the next unsigned <code>short</code> value from the source
-     *         stream.
-     * 
+     * Reads an unsigned 16-bit short from the current position in this file and
+     * returns it as an integer. Blocks until two bytes have been read, the end of
+     * the file is reached or an exception is thrown.
+     * 
+     * @return the next unsigned short value from this file as an int.
+     * @throws EOFException
+     *             if the end of this file is detected.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeShort(int)
+     *             if this file is closed or another I/O error occurs.
+     * @see #writeShort(int)
      */
     public final int readUnsignedShort() throws IOException {
         byte[] buffer = new byte[2];
@@ -607,14 +647,21 @@
     }
 
     /**
-     * Reads a UTF format String from this Stream.
-     * 
-     * @return String the next UTF String from the source stream.
-     * 
-     * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeUTF(java.lang.String)
+     * Reads a string that is encoded in {@link DataInput modified UTF-8} from
+     * this file. The number of bytes that must be read for the complete string
+     * is determined by the first two bytes read from the file. Blocks until all
+     * required bytes have been read, the end of the file is reached or an
+     * exception is thrown.
+     * 
+     * @return the next string encoded in {@link DataInput modified UTF-8} from
+     *         this file.
+     * @throws EOFException
+     *             if the end of this file is detected.
+     * @throws IOException
+     *             if this file is closed or another I/O error occurs.
+     * @throws UTFDataFormatException
+     *             if the bytes read cannot be decoded into a character string.
+     * @see #writeUTF(String)
      */
     public final String readUTF() throws IOException {
         int utfSize = readUnsignedShort();
@@ -629,14 +676,16 @@
     }
 
     /**
-     * Seeks to the position <code>pos</code> in this RandomAccessFile. All
-     * read/write/skip methods sent will be relative to <code>pos</code>.
+     * Moves this file's file pointer to a new position, from where following
+     * {@code read}, {@code write} or {@code skip} operations are done. The
+     * position may be greater than the current length of the file, but the
+     * file's length will only change if the moving of the pointer is followed
+     * by a {@code write} operation.
      * 
      * @param pos
-     *            the desired file pointer position
-     * 
+     *            the new file pointer position.
      * @throws IOException
-     *             If the stream is already closed or another IOException
+     *             if this file is closed, {@code pos < 0} or another I/O error
      *             occurs.
      */
     public void seek(long pos) throws IOException {
@@ -651,17 +700,18 @@
     }
 
     /**
-     * Set the length of this file to be <code>newLength</code>. If the
-     * current file is smaller, it will be expanded and the filePosition will be
-     * set to the new file length. If the <code>newLength</code> is smaller
-     * then the file will be truncated.
+     * Sets the length of this file to {@code newLength}. If the current file is
+     * smaller, it is expanded but the contents from the previous end of the
+     * file to the new end are undefined. The file is truncated if its current
+     * size is bigger than {@code newLength}. If the current file pointer
+     * position is in the truncated part, it is set to the end of the file.
      * 
      * @param newLength
-     *            the desired file length
-     * 
+     *            the new file length in bytes.
+     * @throws IllegalArgumentException
+     *             if {@code newLength < 0}.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this file is closed or another I/O error occurs.
      */
     public void setLength(long newLength) throws IOException {
         openCheck();
@@ -682,17 +732,16 @@
     }
 
     /**
-     * Skips <code>count</code> number of bytes in this stream. Subsequent
-     * <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used.
+     * Skips over {@code count} bytes in this file. Less than {@code count}
+     * bytes are skipped if the end of the file is reached or an exception is
+     * thrown during the operation. Nothing is done if {@code count} is
+     * negative.
      * 
      * @param count
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this file is closed or another I/O error occurs.
      */
     public int skipBytes(int count) throws IOException {
         if (count > 0) {
@@ -706,44 +755,40 @@
     }
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to
-     * this RandomAccessFile starting at the current file pointer.
+     * Writes the entire contents of the byte array {@code buffer} to this file,
+     * starting at the current file pointer.
      * 
      * @param buffer
-     *            the buffer to be written.
-     * 
+     *            the buffer to write.
      * @throws IOException
-     *             If an error occurs trying to write to this RandomAccessFile.
-     * 
-     * @see #read()
+     *             if an I/O error occurs while writing to this file.
      * @see #read(byte[])
-     * @see #read(byte[], int, int)
+     * @see #read(byte[],int,int)
+     * @see #readFully(byte[])
+     * @see #readFully(byte[],int,int)
      */
     public void write(byte[] buffer) throws IOException {
         write(buffer, 0, buffer.length);
     }
 
     /**
-     * Writes <code>count</code> bytes from the byte array <code>buffer</code>
-     * starting at <code>offset</code> to this RandomAccessFile starting at
-     * the current file pointer..
+     * Writes {@code count} bytes from the byte array {@code buffer} to this
+     * file, starting at the current file pointer and using {@code offset} as
+     * the first position within {@code buffer} to get bytes.
      * 
      * @param buffer
-     *            the bytes to be written
+     *            the buffer to write to this file.
      * @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 IOException
-     *             If an error occurs attempting to write to this
-     *             RandomAccessFile.
+     *            the number of bytes from {@code buffer} to write.
      * @throws IndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
-     * 
-     * @see #read()
-     * @see #read(byte[])
+     *             if {@code count < 0}, {@code offset < 0} or {@code count +
+     *             offset} is greater than the size of {@code buffer}.
+     * @throws IOException
+     *             if an I/O error occurs while writing to this file.
      * @see #read(byte[], int, int)
+     * @see #readFully(byte[], int, int)
      */
     public void write(byte[] buffer, int offset, int count) throws IOException {
         if (count > buffer.length - offset || count < 0 || offset < 0) {
@@ -763,20 +808,14 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this RandomAccessFile
-     * starting at the current file pointer. Only the low order byte of
-     * <code>oneByte</code> is written.
+     * Writes a byte to this file, starting at the current file pointer. Only
+     * the least significant byte of the integer {@code oneByte} is written.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             RandomAccessFile.
-     * 
+     *             if this file is closed or another I/O error occurs.
      * @see #read()
-     * @see #read(byte[])
-     * @see #read(byte[], int, int)
      */
     public void write(int oneByte) throws IOException {
         openCheck();
@@ -793,31 +832,26 @@
     }
 
     /**
-     * Writes a boolean to this output stream.
+     * Writes a boolean to this file, starting at the current file pointer.
      * 
      * @param val
-     *            the boolean value to write to the OutputStream
-     * 
+     *            the boolean to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readBoolean()
+     *             if this file is closed or another I/O error occurs.
+     * @see #readBoolean()
      */
     public final void writeBoolean(boolean val) throws IOException {
         write(val ? 1 : 0);
     }
 
     /**
-     * Writes a 8-bit byte to this output stream.
+     * Writes an 8-bit byte to this file, starting at the current file pointer.
+     * Only the least significant byte of the integer {@code val} is written.
      * 
      * @param val
-     *            the byte value to write to the OutputStream
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
+     *            the byte to write to this file.
+     * @throws IOException
+     *             if this file is closed or another I/O error occurs.
      * @see #readByte()
      * @see #readUnsignedByte()
      */
@@ -826,15 +860,13 @@
     }
 
     /**
-     * Writes the low order 8-bit bytes from a String to this output stream.
+     * Writes the low order 8-bit bytes from a string to this file, starting at
+     * the current file pointer.
      * 
      * @param str
-     *            the String containing the bytes to write to the OutputStream
-     * 
+     *            the string containing the bytes to write to this file
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
+     *             if an I/O error occurs while writing to this file.
      * @see #read(byte[])
      * @see #read(byte[],int,int)
      * @see #readFully(byte[])
@@ -849,18 +881,15 @@
     }
 
     /**
-     * Writes the specified 16-bit character to the OutputStream. Only the lower
-     * 2 bytes are written with the higher of the 2 bytes written first. This
-     * represents the Unicode value of val.
+     * Writes a 16-bit character to this file, starting at the current file
+     * pointer. Only the two least significant bytes of the integer {@code val}
+     * are written, with the high byte first.
      * 
      * @param val
-     *            the character to be written
-     * 
+     *            the char to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readChar()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readChar()
      */
     public final void writeChar(int val) throws IOException {
         byte[] buffer = new byte[2];
@@ -870,19 +899,15 @@
     }
 
     /**
-     * Writes the specified 16-bit characters contained in str to the
-     * OutputStream. Only the lower 2 bytes of each character are written with
-     * the higher of the 2 bytes written first. This represents the Unicode
-     * value of each character in str.
+     * Writes the 16-bit characters from a string to this file, starting at the
+     * current file pointer. Each character is written in the same way as with
+     * {@link #writeChar(int)}, with its high byte first.
      * 
      * @param str
-     *            the String whose characters are to be written.
-     * 
+     *            the string to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readChar()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readChar()
      */
     public final void writeChars(String str) throws IOException {
         byte newBytes[] = new byte[str.length() * 2];
@@ -895,51 +920,45 @@
     }
 
     /**
-     * Writes a 64-bit double to this output stream. The resulting output is the
-     * 8 bytes resulting from calling Double.doubleToLongBits().
+     * Writes a 64-bit double to this file, starting at the current file
+     * pointer. The eight bytes returned by
+     * {@link Double#doubleToLongBits(double)} are written to this file.
      * 
      * @param val
-     *            the double to be written.
-     * 
+     *            the double to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readDouble()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readDouble()
      */
     public final void writeDouble(double val) throws IOException {
         writeLong(Double.doubleToLongBits(val));
     }
 
     /**
-     * Writes a 32-bit float to this output stream. The resulting output is the
-     * 4 bytes resulting from calling Float.floatToIntBits().
+     * Writes a 32-bit float to this file, starting at the current file pointer.
+     * The four bytes returned by {@link Float#floatToIntBits(float)} are
+     * written to this file.
      * 
      * @param val
-     *            the float to be written.
-     * 
+     *            the float to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readFloat()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readFloat()
      */
     public final void writeFloat(float val) throws IOException {
         writeInt(Float.floatToIntBits(val));
     }
 
     /**
-     * Writes a 32-bit int to this output stream. The resulting output is the 4
-     * bytes, highest order first, of val.
+     * Writes a 32-bit integer to this file, starting at the current file
+     * pointer. The four bytes of the integer are written with the highest byte
+     * first.
      * 
      * @param val
-     *            the int to be written.
-     * 
+     *            the int to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readInt()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readInt()
      */
     public final void writeInt(int val) throws IOException {
         byte[] buffer = new byte[4];
@@ -951,17 +970,15 @@
     }
 
     /**
-     * Writes a 64-bit long to this output stream. The resulting output is the 8
-     * bytes, highest order first, of val.
+     * Writes a 64-bit long to this file, starting at the current file
+     * pointer. The eight bytes of the long are written with the highest byte
+     * first.
      * 
      * @param val
-     *            the long to be written.
-     * 
+     *            the long to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readLong()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readLong()
      */
     public final void writeLong(long val) throws IOException {
         byte[] buffer = new byte[8];
@@ -978,17 +995,15 @@
     }
 
     /**
-     * Writes the specified 16-bit short to the OutputStream. Only the lower 2
-     * bytes are written with the higher of the 2 bytes written first.
+     * Writes a 16-bit short to this file, starting at the current file
+     * pointer. Only the two least significant bytes of the integer {@code val}
+     * are written, with the high byte first.
      * 
      * @param val
-     *            the short to be written
-     * 
+     *            the short to write to this file.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readShort()
+     *             if an I/O error occurs while writing to this file.
+     * @see #readShort()
      * @see DataInput#readUnsignedShort()
      */
     public final void writeShort(int val) throws IOException {
@@ -996,16 +1011,17 @@
     }
 
     /**
-     * Writes the specified String out in UTF format.
+     * Writes a string encoded with {@link DataInput modified UTF-8} to this
+     * file, starting at the current file pointer.
      * 
      * @param str
-     *            the String to be written in UTF format.
-     * 
+     *            the string to write in {@link DataInput modified UTF-8}
+     *            format.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readUTF()
+     *             if an I/O error occurs while writing to this file.
+     * @throws UTFDataFormatException
+     *             if the encoded string is longer than 65535 bytes.
+     * @see #readUTF()
      */
     public final void writeUTF(String str) throws IOException {
         int utfCount = 0, length = str.length();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Reader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Reader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Reader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Reader.java Fri May  1 08:08:59 2009
@@ -21,9 +21,18 @@
 import java.nio.ReadOnlyBufferException;
 
 /**
- * Reader is an Abstract class for reading Character Streams. Subclasses of
- * Reader must implement the methods <code>read(char[], int, int)</code> and
- * <code>close()</code>.
+ * The base class for all readers. A reader is a means of reading data from a
+ * source in a character-wise manner. Some readers also support marking a
+ * position in the input and returning to this position later.
+ * <p>
+ * This abstract class does not provide a fully working implementation, so it
+ * needs to be subclassed, and at least the {@link #read(char[], int, int)} and
+ * {@link #close()} methods needs to be overridden. Overriding some of the
+ * non-abstract methods is also often advised, since it might result in higher
+ * efficiency.
+ * <p>
+ * Many specialized readers for purposes like reading from a file already exist
+ * in this package.
  * 
  * @see Writer
  */
@@ -34,8 +43,8 @@
     protected Object lock;
 
     /**
-     * Constructs a new character stream Reader using <code>this</code> as the
-     * Object to synchronize critical regions around.
+     * Constructs a new {@code Reader} with {@code this} as the object used to
+     * synchronize critical sections.
      */
     protected Reader() {
         super();
@@ -43,12 +52,13 @@
     }
 
     /**
-     * Constructs a new character stream Reader using <code>lock</code> as the
-     * Object to synchronize critical regions around.
+     * Constructs a new {@code Reader} with {@code lock} used to synchronize
+     * critical sections.
      * 
      * @param lock
-     *            the <code>Object</code> to synchronize critical regions
-     *            around.
+     *            the {@code Object} used to synchronize critical sections.
+     * @throws NullPointerException
+     *             if {@code lock} is {@code null}.
      */
     protected Reader(Object lock) {
         if (lock == null) {
@@ -58,56 +68,57 @@
     }
 
     /**
-     * Close this Reader. This must be implemented by any concrete subclasses.
-     * The implementation should free any resources associated with the Reader.
+     * Closes this reader. Implementations of this method should free any
+     * resources associated with the reader.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this Reader.
+     *             if an error occurs while closing this reader.
      */
     public abstract void close() throws IOException;
 
     /**
-     * Set a Mark position in this Reader. 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.
+     * Sets a mark position in this reader. The parameter {@code readLimit}
+     * indicates how many characters can be read before the mark is invalidated.
+     * Calling {@code reset()} will reposition the reader back to the marked
+     * position if {@code readLimit} has not been surpassed.
      * <p>
-     * This default implementation simply throws IOException and concrete
-     * subclasses must provide their own implementations.
+     * This default implementation simply throws an {@code IOException};
+     * subclasses must provide their own implementation.
      * 
      * @param readLimit
-     *            an int representing how many characters must be read before
-     *            invalidating the mark.
-     * 
-     * @throws IOException
-     *             If an error occurs attempting mark this Reader.
+     *            the number of characters that can be read before the mark is
+     *            invalidated.
+     * @throws IllegalArgumentException
+     *             if {@code readLimit < 0}.
+     * @throws IOException
+     *             if an error occurs while setting a mark in this reader.
+     * @see #markSupported()
+     * @see #reset()
      */
     public void mark(int readLimit) throws IOException {
         throw new IOException();
     }
 
     /**
-     * Answers a boolean indicating whether or not this Reader supports mark()
-     * and reset(). This class a default implementation which answers false.
+     * Indicates whether this reader supports the {@code mark()} and
+     * {@code reset()} methods. This default implementation returns
+     * {@code false}.
      * 
-     * @return <code>true</code> if mark() and reset() are supported,
-     *         <code>false</code> otherwise. This implementation returns
-     *         <code>false</code>.
+     * @return always {@code false}.
      */
     public boolean markSupported() {
         return false;
     }
 
     /**
-     * Reads a single character from this reader and returns the result as an
-     * int. The 2 higher-order characters are set to 0. If the end of reader was
-     * encountered then return -1.
-     * 
-     * @return the character read or -1 if end of reader.
+     * Reads a single character from this reader and returns it as an integer
+     * with the two higher-order bytes set to 0. Returns -1 if the end of the
+     * reader has been reached.
      * 
+     * @return the character read or -1 if the end of the reader has been
+     *         reached.
      * @throws IOException
-     *             If the Reader is already closed or some other IO error
-     *             occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     public int read() throws IOException {
         synchronized (lock) {
@@ -120,93 +131,91 @@
     }
 
     /**
-     * Reads characters from this Reader and stores them in the character array
-     * <code>buf</code> starting at offset 0. Returns the number of characters
-     * actually read or -1 if the end of reader was encountered.
+     * Reads characters from this reader and stores them in the character array
+     * {@code buf} starting at offset 0. Returns the number of characters
+     * actually read or -1 if the end of the reader has been reached.
      * 
      * @param buf
-     *            character array to store the read characters
-     * @return how many characters were successfully read in or else -1 if the
-     *         end of the reader was detected.
-     * 
+     *            character array to store the characters read.
+     * @return the number of characters read or -1 if the end of the reader has
+     *         been reached.
      * @throws IOException
-     *             If the Reader is already closed or some other IO error
-     *             occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     public int read(char buf[]) throws IOException {
         return read(buf, 0, buf.length);
     }
 
     /**
-     * Reads at most <code>count</code> characters from this Reader and stores
-     * them at <code>offset</code> in the character array <code>buf</code>.
-     * Returns the number of characters actually read or -1 if the end of reader
-     * was encountered.
+     * Reads at most {@code count} characters from this reader and stores them
+     * at {@code offset} in the character array {@code buf}. Returns the number
+     * of characters actually read or -1 if the end of the reader has been
+     * reached.
      * 
      * @param buf
-     *            character array to store the read characters
+     *            the character array to store the characters read.
      * @param offset
-     *            offset in buf to store the read characters
+     *            the initial position in {@code buffer} to store the characters
+     *            read from this reader.
      * @param count
-     *            how many characters should be read in
-     * @return how many characters were successfully read in or else -1 if the
-     *         end of the reader was detected.
-     * 
+     *            the maximum number of characters to read.
+     * @return the number of characters read or -1 if the end of the reader has
+     *         been reached.
      * @throws IOException
-     *             If the Reader is already closed or some other IO error
-     *             occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     public abstract int read(char buf[], int offset, int count)
             throws IOException;
 
     /**
-     * Answers a <code>boolean</code> indicating whether or not this Reader is
-     * ready to be read without blocking. If the result is <code>true</code>,
-     * the next <code>read()</code> will not block. If the result is
-     * <code>false</code> this Reader may or may not block when
-     * <code>read()</code> is sent.
-     * 
-     * @return <code>true</code> if the receiver will not block when
-     *         <code>read()</code> is called, <code>false</code> if unknown
-     *         or blocking will occur.
-     * 
-     * @throws IOException
-     *             If the Reader is already closed or some other IO error
-     *             occurs.
+     * Indicates whether this reader is ready to be read without blocking.
+     * Returns {@code true} if this reader will not block when {@code read} is
+     * called, {@code false} if unknown or blocking will occur. This default
+     * implementation always returns {@code false}.
+     * 
+     * @return always {@code false}.
+     * @throws IOException
+     *             if this reader is closed or some other I/O error occurs.
+     * @see #read()
+     * @see #read(char[])
+     * @see #read(char[], int, int)
      */
     public boolean ready() throws IOException {
         return false;
     }
 
     /**
-     * Reset this Readers position to the last <code>mark()</code> location.
-     * Invocations of <code>read()/skip()</code> will occur from this new
-     * location. If this Reader was not marked, the implementation of
-     * <code>reset()</code> is implementation specific. See the comment for
-     * the specific Reader subclass for implementation details. The default
-     * action is to throw <code>IOException</code>.
+     * Resets this reader's position to the last {@code mark()} location.
+     * Invocations of {@code read()} and {@code skip()} will occur from this new
+     * location. If this reader has not been marked, the behavior of
+     * {@code reset()} is implementation specific. This default
+     * implementation throws an {@code IOException}.
      * 
      * @throws IOException
-     *             If a problem occurred or the receiver does not support
-     *             <code>mark()/reset()</code>.
+     *             always thrown in this default implementation.
+     * @see #mark(int)
+     * @see #markSupported()
      */
     public void reset() throws IOException {
         throw new IOException();
     }
 
     /**
-     * Skips <code>count</code> number of characters in this Reader.
-     * Subsequent <code>read()</code>'s will not return these characters
-     * unless <code>reset()</code> is used. This method may perform multiple
-     * reads to read <code>count</code> characters.
+     * Skips {@code amount} characters in this reader. Subsequent calls of
+     * {@code read} methods will not return these characters unless {@code
+     * reset()} is used. This method may perform multiple reads to read {@code
+     * count} characters.
      * 
      * @param count
-     *            how many characters should be passed over
-     * @return how many characters were successfully passed over
-     * 
-     * @throws IOException
-     *             If the Reader is closed when the call is made or if an IO
-     *             error occurs during the operation.
+     *            the maximum number of characters to skip.
+     * @return the number of characters actually skipped.
+     * @throws IllegalArgumentException
+     *             if {@code amount < 0}.
+     * @throws IOException
+     *             if this reader is closed or some other I/O error occurs.
+     * @see #mark(int)
+     * @see #markSupported()
+     * @see #reset()
      */
     public long skip(long count) throws IOException {
         if (count < 0) {
@@ -234,19 +243,18 @@
     }
 
     /**
-     * Read chars from the Reader and then put them to the <code>target</code>
-     * CharBuffer. Only put method is called on the <code>target</code>.
+     * Reads characters and puts them into the {@code target} character buffer.
      * 
      * @param target
-     *            the destination CharBuffer
-     * @return the actual number of chars put to the <code>target</code>. -1
-     *         when the Reader has reached the end before the method is called.
+     *            the destination character buffer.
+     * @return the number of characters put into {@code target} or -1 if the end
+     *         of this reader has been reached before a character has been read.
      * @throws IOException
-     *             if any I/O error raises in the procedure
+     *             if any I/O error occurs while reading from this reader.
      * @throws NullPointerException
-     *             if the target CharBuffer is null
+     *             if {@code target} is {@code null}.
      * @throws ReadOnlyBufferException
-     *             if the target CharBuffer is readonly
+     *             if {@code target} is read-only.
      */
     public int read(CharBuffer target) throws IOException {
         if (null == target) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SequenceInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SequenceInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SequenceInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SequenceInputStream.java Fri May  1 08:08:59 2009
@@ -21,10 +21,9 @@
 import java.util.Vector;
 
 /**
- * SequenceInputStream is used for streaming over a sequence of streams
- * concatenated together. Reads are taken from the first stream until it ends,
- * then the next stream is used until the last stream returns end of file.
- * 
+ * Concatenates two or more existing {@link InputStream}s. Reads are taken from
+ * the first stream until it ends, then the next stream is used, until the last
+ * stream returns end of file.
  */
 public class SequenceInputStream extends InputStream {
     /**
@@ -38,14 +37,15 @@
     private InputStream in;
 
     /**
-     * Constructs a new SequenceInputStream using the two streams
-     * <code>s1</code> and <code>s2</code> as the sequence of streams to
-     * read from.
+     * Constructs a new {@code SequenceInputStream} using the two streams
+     * {@code s1} and {@code s2} as the sequence of streams to read from.
      * 
      * @param s1
-     *            the first stream to get bytes from
+     *            the first stream to get bytes from.
      * @param s2
-     *            the second stream to get bytes from
+     *            the second stream to get bytes from.
+     * @throws NullPointerException
+     *             if {@code s1} is {@code null}.
      */
     public SequenceInputStream(InputStream s1, InputStream s2) {
         if (s1 == null) {
@@ -59,11 +59,13 @@
 
     /**
      * Constructs a new SequenceInputStream using the elements returned from
-     * Enumeration <code>e</code> as the stream sequence. The types returned
-     * from nextElement() must be of InputStream.
+     * Enumeration {@code e} as the stream sequence. The instances returned by
+     * {@code e.nextElement()} must be of type {@link InputStream}.
      * 
      * @param e
-     *            the Enumeration of InputStreams to get bytes from
+     *            the enumeration of {@code InputStreams} to get bytes from.
+     * @throws NullPointerException
+     *             if any of the elements in {@code e} is {@code null}.
      */
     public SequenceInputStream(Enumeration<? extends InputStream> e) {
         this.e = e;
@@ -76,13 +78,12 @@
     }
 
     /**
-     * Answers a int representing then number of bytes that are available before
-     * this InputStream will block.
-     * 
-     * @return the number of bytes available before blocking.
+     * Returns the number of bytes that are available before the current input stream will
+     * block.
      * 
+     * @return the number of bytes available in the current input stream before blocking.
      * @throws IOException
-     *             If an error occurs in this InputStream.
+     *             if an I/O error occurs in the current input stream.
      */
     @Override
     public int available() throws IOException {
@@ -93,12 +94,10 @@
     }
 
     /**
-     * Close the SequenceInputStream. All streams in this sequence are closed
-     * before returning from this method. This stream cannot be used for input
-     * once it has been closed.
+     * Closes all streams in this sequence of input stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this FileInputStream.
+     *             if an error occurs while closing any of the input streams.
      */
     @Override
     public void close() throws IOException {
@@ -128,15 +127,18 @@
     }
 
     /**
-     * Reads a single byte from this SequenceInputStream and returns the result
-     * as an int. The low-order byte is returned or -1 of the end of stream was
-     * encountered. The current stream is read from. If it reaches the end of
-     * file, the next stream is read from.
-     * 
-     * @return the byte read or -1 if end of stream.
-     * 
+     * Reads a single byte from this sequence of input streams and returns it as
+     * an integer in the range from 0 to 255. It tries to read from the current
+     * stream first; if the end of this stream has been reached, it reads from
+     * the next one. Blocks until one byte has been read, the end of the last
+     * input stream in the sequence has been reached, or an exception is thrown.
+     * 
+     * @return the byte read or -1 if either the end of the last stream in the
+     *         sequence has been reached or this input stream sequence is
+     *         closed.
      * @throws IOException
-     *             If an error occurs while reading the stream
+     *             if an error occurs while reading the current source input
+     *             stream.
      */
     @Override
     public int read() throws IOException {
@@ -151,21 +153,39 @@
     }
 
     /**
-     * Reads at most <code>count</code> bytes from this SequenceInputStream
-     * and stores them in byte array <code>buffer</code> starting at
-     * <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 count} bytes from this sequence of input streams and
+     * stores them in the byte array {@code buffer} starting at {@code offset}.
+     * Blocks only until at least 1 byte has been read, the end of the stream
+     * has been reached, or an exception is thrown.
+     * <p>
+     * This SequenceInputStream shows the same behavior as other InputStreams.
+     * To do this it will read only as many bytes as a call to read on the
+     * current substream returns. If that call does not return as many bytes as
+     * requested by {@code count}, it will not retry to read more on its own
+     * because subsequent reads might block. This would violate the rule that
+     * it will only block until at least one byte has been read.
+     * <p>
+     * If a substream has already reached the end when this call is made, it
+     * will close that substream and start with the next one. If there are no
+     * more substreams it will return -1.
      * 
      * @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 stream.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes actually read; -1 if this sequence of streams
+     *         is closed or if the end of the last stream in the sequence has
+     *         been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the size of {@code buffer}.
      * @throws IOException
-     *             If an error occurs while reading the stream
+     *             if an I/O error occurs.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     @Override
     public int read(byte[] buffer, int offset, int count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Serializable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Serializable.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Serializable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Serializable.java Fri May  1 08:08:59 2009
@@ -18,8 +18,19 @@
 package java.io;
 
 /**
- * Objects that want to be serialized/deserialized using
- * ObjectOutputStream/ObjectInputStream should implement this interface.
+ * An empty marker interface for classes that want to support serialization and
+ * deserialization based on the {@code ObjectOutputStream} and {@code
+ * ObjectInputStream} classes. Implementing this interface is enough to make
+ * most classes serializable. If a class needs more fine-grained control over
+ * the serialization process (for example to implement compatibility with older
+ * versions of the class), it can achieve this by providing the following two
+ * methods (signatures must match exactly):
+ * <p>
+ * {@code private void writeObject(java.io.ObjectOutputStream out) throws
+ * IOException}
+ * <p>
+ * {@code private void readObject(java.io.ObjectInputStream in) throws
+ * IOException, ClassNotFoundException}
  */
 public interface Serializable {
     /* empty */

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SerializablePermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SerializablePermission.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SerializablePermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SerializablePermission.java Fri May  1 08:08:59 2009
@@ -20,14 +20,19 @@
 import java.security.BasicPermission;
 
 /**
- * SerializablePermission objects represent permission to access unsafe
- * serialization operations. The name of the permission should be one of:
- * <dl>
- * <dt>enableSubclassImplementation</dt>
- * <dd>Subclasses can override serialization behavior</dd>
- * <dt>enableSubstitution</dt>
- * <dd>Object substitution can be enabled</dd>
- * </dl>
+ * Is used to enable access to potentially unsafe serialization operations. It
+ * does have a name but no action list. The following table lists valid
+ * permission names:
+ * <table>
+ * <tr>
+ * <td>enableSubclassImplementation</td>
+ * <td>Subclasses can override serialization behavior.</td>
+ * </tr>
+ * <tr>
+ * <td>enableSubstitution</td>
+ * <td>Object substitution is allowed.</td>
+ * </tr>
+ * </table>
  * 
  * @see ObjectStreamConstants
  */
@@ -39,7 +44,7 @@
     private String actions;
 
     /**
-     * Creates an instance of this class with the given name.
+     * Constructs a new {@code SerializablePermission} with the specified name.
      * 
      * @param permissionName
      *            the name of the new permission.
@@ -49,7 +54,7 @@
     }
 
     /**
-     * Creates an instance of this class with the given name and action list.
+     * Constructs a new {@code SerializablePermission} with the specified name.
      * The action list is ignored.
      * 
      * @param name

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamCorruptedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamCorruptedException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamCorruptedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamCorruptedException.java Fri May  1 08:08:59 2009
@@ -18,31 +18,32 @@
 package java.io;
 
 /**
- * When readObject() cannot read an object from the input stream due to missing
- * information (cyclic reference that doesn't match previous instance or missing
- * class descriptor for instance to be loaded) this type of exception is thrown.
+ * Signals that the {@link ObjectInputStream#readObject()} method could not
+ * read an object due to missing information (for example, a cyclic reference
+ * that doesn't match a previous instance, or a missing class descriptor for the
+ * object to be loaded).
  * 
  * @see ObjectInputStream
  * @see OptionalDataException
- * 
  */
 public class StreamCorruptedException extends ObjectStreamException {
 
     private static final long serialVersionUID = 8983558202217591746L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code StreamCorruptedException} with its stack trace
+     * filled in.
      */
     public StreamCorruptedException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code StreamCorruptedException} with its stack trace
+     * and detail message filled in.
      * 
      * @param detailMessage
-     *            the detail message for the exception.
+     *            the detail message for this exception.
      */
     public StreamCorruptedException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamTokenizer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamTokenizer.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamTokenizer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamTokenizer.java Fri May  1 08:08:59 2009
@@ -18,44 +18,32 @@
 package java.io;
 
 /**
- * StreamTokenizer takes a stream and a set of tokens and parses them one at a
- * time. The different types of tokens that can be found are numbers,
- * identifiers, quoted strings, and different comment styles.
+ * Parses a stream into a set of defined tokens, one at a time. The different
+ * types of tokens that can be found are numbers, identifiers, quoted strings,
+ * and different comment styles. The class can be used for limited processing
+ * of source code of programming languages like Java, although it is nowhere
+ * near a full parser.
  */
 public class StreamTokenizer {
     /**
-     * Contains a number if the current token is a number (<code>ttype</code>
-     * is <code>TT_NUMBER</code>)
+     * Contains a number if the current token is a number ({@code ttype} ==
+     * {@code TT_NUMBER}).
      */
     public double nval;
 
     /**
-     * Contains a string if the current token is a word (<code>ttype</code>
-     * is <code>TT_WORD</code>)
+     * Contains a string if the current token is a word ({@code ttype} ==
+     * {@code TT_WORD}).
      */
     public String sval;
 
     /**
-     * After calling <code>nextToken</code>, the field <code>ttype</code>
-     * contains the type of token that has been read. When a single character is
-     * read, it's integer value is used. For a quoted string, the value is the
-     * quoted character. If not one of those, then it is one of the following:
-     * <UL>
-     * <LI> <code>TT_WORD</code> - the token is a word.</LI>
-     * <LI> <code>TT_NUMBER</code> - the token is a number.</LI>
-     * <LI> <code>TT_EOL</code> - the end of line has been reached. Depends on
-     * whether <code>eolIsSignificant</code> is <code>true</code>.</LI>
-     * <LI> <code>TT_EOF</code> - the end of the stream has been reached.</LI>
-     * </UL>
-     */
-
-    /**
-     * The constant representing end of stream.
+     * The constant representing the end of the stream.
      */
     public static final int TT_EOF = -1;
 
     /**
-     * The constant representing end of line.
+     * The constant representing the end of the line.
      */
     public static final int TT_EOL = '\n';
 
@@ -75,7 +63,18 @@
     private static final int TT_UNKNOWN = -4;
 
     /**
-     * The token type
+     * After calling {@code nextToken()}, {@code ttype} contains the type of
+     * token that has been read. When a single character is read, its value
+     * converted to an integer is stored in {@code ttype}. For a quoted string,
+     * the value is the quoted character. Otherwise, its value is one of the
+     * following:
+     * <ul>
+     * <li> {@code TT_WORD} - the token is a word.</li>
+     * <li> {@code TT_NUMBER} - the token is a number.</li>
+     * <li> {@code TT_EOL} - the end of line has been reached. Depends on
+     * whether {@code eolIsSignificant} is {@code true}.</li>
+     * <li> {@code TT_EOF} - the end of the stream has been reached.</li>
+     * </ul>
      */
     public int ttype = TT_UNKNOWN;
 
@@ -152,13 +151,15 @@
     }
 
     /**
-     * Construct a new StreamTokenizer on the InputStream is. This usage of this
-     * method should be replaced with the constructor which takes a Reader.
+     * Constructs a new {@code StreamTokenizer} with {@code is} as source input
+     * stream. This constructor is deprecated; instead, the constructor that
+     * takes a {@code Reader} as an arugment should be used.
      * 
      * @param is
-     *            The InputStream to parse tokens on.
-     * 
-     * @deprecated Use StreamTokenizer(Reader)
+     *            the source stream from which to parse tokens.
+     * @throws NullPointerException
+     *             if {@code is} is {@code null}.
+     * @deprecated Use {@link #StreamTokenizer(Reader)}
      */
     @Deprecated
     public StreamTokenizer(InputStream is) {
@@ -170,23 +171,23 @@
     }
 
     /**
-     * Construct a new StreamTokenizer on the Reader <code>r</code>.
-     * Initialize the default state per specification.
-     * <UL>
-     * <LI>All byte values 'A' through 'Z', 'a' through 'z', and '&#92;u00A0'
-     * through '&#92;u00FF' are considered to be alphabetic.</LI>
-     * <LI>All byte values '&#92;u0000' through '&#92;u0020' are considered to
-     * be white space. '/' is a comment character.</LI>
-     * <LI>Single quote '\'' and double quote '"' are string quote characters.</LI>
-     * <LI>Numbers are parsed.</LI>
-     * <LI>Ends of lines are considered to be white space rather than separate
-     * tokens.</LI>
-     * <LI>C-style and C++-style comments are not recognized.</LI>
-     * </UL>
-     * These are the defaults and are not needed in constructor.
+     * Constructs a new {@code StreamTokenizer} with {@code r} as source reader.
+     * The tokenizer's initial state is as follows:
+     * <ul>
+     * <li>All byte values 'A' through 'Z', 'a' through 'z', and '&#92;u00A0'
+     * through '&#92;u00FF' are considered to be alphabetic.</li>
+     * <li>All byte values '&#92;u0000' through '&#92;u0020' are considered to
+     * be white space. '/' is a comment character.</li>
+     * <li>Single quote '\'' and double quote '"' are string quote characters.
+     * </li>
+     * <li>Numbers are parsed.</li>
+     * <li>End of lines are considered to be white space rather than separate
+     * tokens.</li>
+     * <li>C-style and C++-style comments are not recognized.</LI>
+     * </ul>
      * 
      * @param r
-     *            The InputStream to parse tokens on.
+     *            the source reader from which to parse tokens.
      */
     public StreamTokenizer(Reader r) {
         this();
@@ -197,11 +198,11 @@
     }
 
     /**
-     * Set the character <code>ch</code> to be regarded as a comment
+     * Specifies that the character {@code ch} shall be treated as a comment
      * character.
      * 
      * @param ch
-     *            The character to be considered a comment character.
+     *            the character to be considered a comment character.
      */
     public void commentChar(int ch) {
         if (0 <= ch && ch < tokenTypes.length) {
@@ -210,45 +211,45 @@
     }
 
     /**
-     * Set a boolean indicating whether or not end of line is significant and
-     * should be returned as <code>TT_EOF</code> in <code>ttype</code>.
+     * Specifies whether the end of a line is significant and should be returned
+     * as {@code TT_EOF} in {@code ttype} by this tokenizer.
      * 
      * @param flag
-     *            <code>true</code> if EOL is significant, <code>false</code>
-     *            otherwise.
+     *            {@code true} if EOL is significant, {@code false} otherwise.
      */
     public void eolIsSignificant(boolean flag) {
         isEOLSignificant = flag;
     }
 
     /**
-     * Answer the current line number.
+     * Returns the current line number.
      * 
-     * @return the current line number.
+     * @return this tokenizer's current line number.
      */
     public int lineno() {
         return lineNumber;
     }
 
     /**
-     * Set a boolean indicating whether or not tokens should be uppercased when
-     * present in <code>sval</code>.
+     * Specifies whether word tokens should be converted to lower case when they
+     * are stored in {@code sval}.
      * 
      * @param flag
-     *            <code>true</code> if <code>sval</code> should be forced
-     *            uppercase, <code>false</code> otherwise.
+     *            {@code true} if {@code sval} should be converted to lower
+     *            case, {@code false} otherwise.
      */
     public void lowerCaseMode(boolean flag) {
         forceLowercase = flag;
     }
 
     /**
-     * Answer the next token type.
-     * 
-     * @return The next token to be parsed.
+     * Parses the next token from this tokenizer's source stream or reader. The
+     * type of the token is stored in the {@code ttype} field, additional
+     * information may be stored in the {@code nval} or {@code sval} fields.
      * 
+     * @return the value of {@code ttype}.
      * @throws IOException
-     *             If an IO error occurs while getting the token
+     *             if an I/O error occurs while parsing the next token.
      */
     public int nextToken() throws IOException {
         if (pushBackToken) {
@@ -476,11 +477,13 @@
     }
 
     /**
-     * Set the character <code>ch</code> to be regarded as an ordinary
-     * character.
+     * Specifies that the character {@code ch} shall be treated as an ordinary
+     * character by this tokenizer. That is, it has no special meaning as a
+     * comment character, word component, white space, string delimiter or
+     * number.
      * 
      * @param ch
-     *            The character to be considered an ordinary comment character.
+     *            the character to be considered an ordinary character.
      */
     public void ordinaryChar(int ch) {
         if (0 <= ch && ch < tokenTypes.length) {
@@ -489,13 +492,15 @@
     }
 
     /**
-     * Set the characters ranging from <code>low</code> to <code>hi</code>
-     * to be regarded as ordinary characters.
+     * Specifies that the characters in the range from {@code low} to {@code hi}
+     * shall be treated as an ordinary character by this tokenizer. That is,
+     * they have no special meaning as a comment character, word component,
+     * white space, string delimiter or number.
      * 
      * @param low
-     *            The starting range for ordinary characters.
+     *            the first character in the range of ordinary characters.
      * @param hi
-     *            The ending range for ordinary characters.
+     *            the last character in the range of ordinary characters.
      */
     public void ordinaryChars(int low, int hi) {
         if (low < 0) {
@@ -510,7 +515,7 @@
     }
 
     /**
-     * Indicate that numbers should be parsed.
+     * Specifies that this tokenizer shall parse numbers.
      */
     public void parseNumbers() {
         for (int i = '0'; i <= '9'; i++) {
@@ -521,18 +526,19 @@
     }
 
     /**
-     * Indicate that the current token should be pushed back and returned the
-     * next time <code>nextToken()</code> is called.
+     * Indicates that the current token should be pushed back and returned again
+     * the next time {@code nextToken()} is called.
      */
     public void pushBack() {
         pushBackToken = true;
     }
 
     /**
-     * Set the character <code>ch</code> to be regarded as a quote character.
+     * Specifies that the character {@code ch} shall be treated as a quote
+     * character.
      * 
      * @param ch
-     *            The character to be considered a quote comment character.
+     *            the character to be considered a quote character.
      */
     public void quoteChar(int ch) {
         if (0 <= ch && ch < tokenTypes.length) {
@@ -549,7 +555,7 @@
     }
 
     /**
-     * Reset all characters so that they are ordinary.
+     * Specifies that all characters shall be treated as ordinary characters.
      */
     public void resetSyntax() {
         for (int i = 0; i < 256; i++) {
@@ -558,34 +564,34 @@
     }
 
     /**
-     * Set a boolean indicating whether or not slash slash comments should be
-     * recognized. The comment ends at a new line.
+     * Specifies whether "slash-slash" (C++-style) comments shall be recognized.
+     * This kind of comment ends at the end of the line.
      * 
      * @param flag
-     *            <code>true</code> if <code>//</code> should be recognized
-     *            as the start of a comment, <code>false</code> otherwise.
+     *            {@code true} if {@code //} should be recognized as the start
+     *            of a comment, {@code false} otherwise.
      */
     public void slashSlashComments(boolean flag) {
         slashSlashComments = flag;
     }
 
     /**
-     * Set a boolean indicating whether or not slash star comments should be
-     * recognized. Slash-star comments cannot be nested and end when a
-     * star-slash combination is found.
+     * Specifies whether "slash-star" (C-style) comments shall be recognized.
+     * Slash-star comments cannot be nested and end when a star-slash
+     * combination is found.
      * 
      * @param flag
-     *            <code>true</code> if <code>/*</code> should be recognized
-     *            as the start of a comment, <code>false</code> otherwise.
+     *            {@code true} if {@code /*} should be recognized as the start
+     *            of a comment, {@code false} otherwise.
      */
     public void slashStarComments(boolean flag) {
         slashStarComments = flag;
     }
 
     /**
-     * Answer the state of this tokenizer in a readable format.
+     * Returns the state of this tokenizer in a readable format.
      * 
-     * @return The current state of this tokenizer.
+     * @return the current state of this tokenizer.
      */
     @Override
     public String toString() {
@@ -621,13 +627,13 @@
     }
 
     /**
-     * Set the characters ranging from <code>low</code> to <code>hi</code>
-     * to be regarded as whitespace characters.
+     * Specifies that the characters in the range from {@code low} to {@code hi}
+     * shall be treated as whitespace characters by this tokenizer.
      * 
      * @param low
-     *            The starting range for whitespace characters.
+     *            the first character in the range of whitespace characters.
      * @param hi
-     *            The ending range for whitespace characters.
+     *            the last character in the range of whitespace characters.
      */
     public void whitespaceChars(int low, int hi) {
         if (low < 0) {
@@ -642,13 +648,14 @@
     }
 
     /**
-     * Set the characters ranging from <code>low</code> to <code>hi</code>
-     * to be regarded as word characters.
+     * Specifies that the characters in the range from {@code low} to {@code hi}
+     * shall be treated as word characters by this tokenizer. A word consists of
+     * a word character followed by zero or more word or number characters.
      * 
      * @param low
-     *            The starting range for word characters.
+     *            the first character in the range of word characters.
      * @param hi
-     *            The ending range for word characters.
+     *            the last character in the range of word characters.
      */
     public void wordChars(int low, int hi) {
         if (low < 0) {



Mime
View raw message