You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/01 10:09:01 UTC
svn commit: r770573 [9/10] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
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 '\u00A0'
- * through '\u00FF' are considered to be alphabetic.</LI>
- * <LI>All byte values '\u0000' through '\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 '\u00A0'
+ * through '\u00FF' are considered to be alphabetic.</li>
+ * <li>All byte values '\u0000' through '\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) {