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 [1/10] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
Author: tellison
Date: Fri May 1 08:08:59 2009
New Revision: 770573
URL: http://svn.apache.org/viewvc?rev=770573&view=rev
Log:
Apply patch HARMONY-6192 (Javadocs from java.io.*)
Modified:
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/File.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileDescriptor.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileFilter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileNotFoundException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermission.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermissionCollection.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotActiveException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotSerializableException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInput.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputValidation.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutput.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamClass.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamConstants.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamField.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OptionalDataException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/RandomAccessFile.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Reader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SequenceInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Serializable.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SerializablePermission.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamCorruptedException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamTokenizer.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringBufferInputStream.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java
harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java Fri May 1 08:08:59 2009
@@ -20,12 +20,19 @@
import org.apache.harmony.luni.util.Msg;
/**
- * <code>BufferedInputStream</code> is a class which takes an input stream and
- * <em>buffers</em> the input. In this way, costly interaction with the original
- * input stream can be minimized by reading buffered amounts of data
- * infrequently. The drawback is that extra space is required to hold the buffer
- * and that copying takes place when reading that buffer.
+ * Wraps an existing {@link InputStream} and <em>buffers</em> the input.
+ * Expensive interaction with the underlying input stream is minimized, since
+ * most (smaller) requests can be satisfied by accessing the buffer alone. The
+ * drawback is that some extra space is required to hold the buffer and that
+ * copying takes place when filling that buffer, but this is usually outweighed
+ * by the performance benefits.
*
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
+ * <pre>
+ * BufferedInputStream buf = new BufferedInputStream(new FileInputStream("file.java"));
+ * </pre>
+ *
* @see BufferedOutputStream
*/
public class BufferedInputStream extends FilterInputStream {
@@ -35,7 +42,7 @@
protected volatile byte[] buf;
/**
- * The total number of bytes inside the byte array <code>buf</code>.
+ * The total number of bytes inside the byte array {@code buf}.
*/
protected int count;
@@ -51,17 +58,17 @@
protected int markpos = -1;
/**
- * The current position within the byte array <code>buf</code>.
+ * The current position within the byte array {@code buf}.
*/
protected int pos;
/**
- * Constructs a new <code>BufferedInputStream</code> on the InputStream
- * <code>in</code>. The default buffer size (8Kb) is allocated and all reads
+ * Constructs a new {@code BufferedInputStream} on the {@link InputStream}
+ * {@code in}. The default buffer size (8 KB) is allocated and all reads
* can now be filtered through this stream.
*
* @param in
- * the InputStream to buffer reads on.
+ * the InputStream the buffer reads from.
*/
public BufferedInputStream(InputStream in) {
super(in);
@@ -69,14 +76,16 @@
}
/**
- * Constructs a new BufferedInputStream on the InputStream <code>in</code>.
- * The buffer size is specified by the parameter <code>size</code> and all
- * reads can now be filtered through this BufferedInputStream.
+ * Constructs a new {@code BufferedInputStream} on the {@link InputStream}
+ * {@code in}. The buffer size is specified by the parameter {@code size}
+ * and all reads are now filtered through this stream.
*
* @param in
- * the InputStream to buffer reads on.
+ * the input stream the buffer reads from.
* @param size
* the size of buffer to allocate.
+ * @throws IllegalArgumentException
+ * if {@code size < 0}.
*/
public BufferedInputStream(InputStream in, int size) {
super(in);
@@ -88,14 +97,13 @@
}
/**
- * Answers an int representing the number of bytes that are available before
- * this BufferedInputStream will block. This method returns the number of
- * bytes available in the buffer plus those available in the target stream.
+ * Returns the number of bytes that are available before this stream will
+ * block. This method returns the number of bytes available in the buffer
+ * plus those available in the source stream.
*
* @return the number of bytes available before blocking.
- *
* @throws IOException
- * If an error occurs in this stream.
+ * if this stream is closed.
*/
@Override
public synchronized int available() throws IOException {
@@ -108,11 +116,11 @@
}
/**
- * Close this BufferedInputStream. This implementation closes the target
- * stream and releases any resources associated with it.
+ * Closes this stream. The source stream is closed and any resources
+ * associated with it are released.
*
* @throws IOException
- * If an error occurs attempting to close this stream.
+ * if an error occurs while closing this stream.
*/
@Override
public void close() throws IOException {
@@ -160,16 +168,17 @@
}
/**
- * Set a Mark position in this BufferedInputStream. The parameter
- * <code>readLimit</code> indicates how many bytes can be read before a mark
- * is invalidated. Sending reset() will reposition the Stream back to the
- * marked position provided <code>readLimit</code> has not been surpassed.
- * The underlying buffer may be increased in size to allow
- * <code>readlimit</code> number of bytes to be supported.
+ * Sets a mark position in this stream. The parameter {@code readlimit}
+ * indicates how many bytes can be read before a mark is invalidated.
+ * Calling {@code reset()} will reposition the stream back to the marked
+ * position if {@code readlimit} has not been surpassed. The underlying
+ * buffer may be increased in size to allow {@code readlimit} number of
+ * bytes to be supported.
*
* @param readlimit
- * the number of bytes to be able to read before invalidating the
- * mark.
+ * the number of bytes that can be read before the mark is
+ * invalidated.
+ * @see #reset()
*/
@Override
public synchronized void mark(int readlimit) {
@@ -178,11 +187,12 @@
}
/**
- * Answers a boolean indicating whether or not this BufferedInputStream
- * supports mark() and reset(). This implementation answers
- * <code>true</code>.
+ * Indicates whether {@code BufferedInputStream} supports the {@code mark()}
+ * and {@code reset()} methods.
*
- * @return <code>true</code> for BufferedInputStreams.
+ * @return {@code true} for BufferedInputStreams.
+ * @see #mark(int)
+ * @see #reset()
*/
@Override
public boolean markSupported() {
@@ -190,16 +200,15 @@
}
/**
- * Reads a single byte from this BufferedInputStream and returns the result
- * as an int. The low-order byte is returned or -1 of the end of stream was
- * encountered. If the underlying buffer does not contain any available
- * bytes then it is filled and the first byte is returned.
- *
- * @return the byte read or -1 if end of stream.
+ * Reads a single byte from this stream and returns it as an integer in the
+ * range from 0 to 255. Returns -1 if the end of the source string has been
+ * reached. If the internal buffer does not contain any available bytes then
+ * it is filled from the source stream and the first byte is returned.
*
+ * @return the byte read or -1 if the end of the source stream has been
+ * reached.
* @throws IOException
- * If the stream is already closed or another IOException
- * occurs.
+ * if this stream is closed or another IOException occurs.
*/
@Override
public synchronized int read() throws IOException {
@@ -233,25 +242,28 @@
}
/**
- * Reads at most <code>length</code> bytes from this BufferedInputStream and
- * stores them in byte array <code>buffer</code> starting at offset
- * <code>offset</code>. Answer the number of bytes actually read or -1 if no
- * bytes were read and end of stream was encountered. If all the buffered
- * bytes have been used, a mark has not been set, and the requested number
- * of bytes is larger than the receiver's buffer size, this implementation
- * bypasses the buffer and simply places the results directly into
- * <code>buffer</code>.
+ * Reads at most {@code length} bytes from this stream and stores them in
+ * byte array {@code buffer} starting at offset {@code offset}. Returns the
+ * number of bytes actually read or -1 if no bytes were read and the end of
+ * the stream was encountered. If all the buffered bytes have been used, a
+ * mark has not been set and the requested number of bytes is larger than
+ * the receiver's buffer size, this implementation bypasses the buffer and
+ * simply places the results directly into {@code buffer}.
*
* @param buffer
- * the byte array in which to store the read bytes.
+ * the byte array in which to store the bytes read.
* @param offset
- * the offset in <code>buffer</code> to store the read bytes.
+ * the initial position in {@code buffer} to store the bytes read
+ * from this stream.
* @param length
- * the maximum number of bytes to store in <code>buffer</code>.
+ * the maximum number of bytes to store in {@code buffer}.
* @return the number of bytes actually read or -1 if end of stream.
- *
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code length < 0}, or if
+ * {@code offset + length} is greater than the size of
+ * {@code buffer}.
* @throws IOException
- * If the stream is already closed or another IOException
+ * if the stream is already closed or another IOException
* occurs.
*/
@Override
@@ -332,13 +344,13 @@
}
/**
- * Reset this BufferedInputStream to the last marked location. If the
- * <code>readlimit</code> has been passed or no <code>mark</code> has been
- * set, throw IOException. This implementation resets the target stream.
+ * Resets this stream to the last marked location.
*
* @throws IOException
- * If the stream is already closed or another IOException
- * occurs.
+ * if this stream is closed, no mark has been set or the mark is
+ * no longer valid because more than {@code readlimit} bytes
+ * have been read since setting the mark.
+ * @see #mark(int)
*/
@Override
public synchronized void reset() throws IOException {
@@ -354,17 +366,16 @@
}
/**
- * Skips <code>amount</code> number of bytes in this BufferedInputStream.
- * Subsequent <code>read()</code>'s will not return these bytes unless
- * <code>reset()</code> is used.
+ * Skips {@code amount} number of bytes in this stream. Subsequent
+ * {@code read()}'s will not return these bytes unless {@code reset()} is
+ * used.
*
* @param amount
- * the number of bytes to skip.
+ * the number of bytes to skip. {@code skip} does nothing and
+ * returns 0 if {@code amount} is less than zero.
* @return the number of bytes actually skipped.
- *
* @throws IOException
- * If the stream is already closed or another IOException
- * occurs.
+ * if this stream is closed or another IOException occurs.
*/
@Override
public synchronized long skip(long amount) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java Fri May 1 08:08:59 2009
@@ -20,32 +20,39 @@
import org.apache.harmony.luni.util.Msg;
/**
- * BufferedOutputStream is a class which takes an output stream and
- * <em>buffers</em> the writes to that stream. In this way, costly interaction
- * with the original output stream can be minimized by writing buffered amounts
- * of data infrequently. The drawback is that extra space is required to hold
- * the buffer and copying takes place when writing that buffer.
+ * Wraps an existing {@link OutputStream} and <em>buffers</em> the output.
+ * Expensive interaction with the underlying input stream is minimized, since
+ * most (smaller) requests can be satisfied by accessing the buffer alone. The
+ * drawback is that some extra space is required to hold the buffer and that
+ * copying takes place when flushing that buffer, but this is usually outweighed
+ * by the performance benefits.
*
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
+ * <pre>
+ * BufferedOutputStream buf = new BufferedOutputStream(new FileOutputStream("file.java"));
+ * </pre>
+ *
* @see BufferedInputStream
*/
public class BufferedOutputStream extends FilterOutputStream {
/**
- * The buffer containing the bytes to be written to the target OutputStream.
+ * The buffer containing the bytes to be written to the target stream.
*/
protected byte[] buf;
/**
- * The total number of bytes inside the byte array <code>buf</code>.
+ * The total number of bytes inside the byte array {@code buf}.
*/
protected int count;
/**
- * Constructs a new BufferedOutputStream on the OutputStream
- * <code>out</code>. The default buffer size (8Kb) is allocated and all
- * writes are now filtered through this stream.
+ * Constructs a new {@code BufferedOutputStream} on the {@link OutputStream}
+ * {@code out}. The buffer size is set to the default value of 8 KB.
*
* @param out
- * the OutputStream to buffer writes on.
+ * the {@code OutputStream} for which write operations are
+ * buffered.
*/
public BufferedOutputStream(OutputStream out) {
super(out);
@@ -53,16 +60,15 @@
}
/**
- * Constructs a new BufferedOutputStream on the OutputStream
- * <code>out</code>. The buffer size is set to <code>size</code> and
- * all writes are now filtered through this stream.
+ * Constructs a new {@code BufferedOutputStream} on the {@link OutputStream}
+ * {@code out}. The buffer size is set to {@code size}.
*
* @param out
- * the OutputStream to buffer writes on.
+ * the output stream for which write operations are buffered.
* @param size
* the size of the buffer in bytes.
* @throws IllegalArgumentException
- * the size is <= 0
+ * if {@code size <= 0}.
*/
public BufferedOutputStream(OutputStream out, int size) {
super(out);
@@ -74,13 +80,11 @@
}
/**
- * Flush this BufferedOutputStream to ensure all pending data is written out
- * to the target OutputStream. In addition, the target stream is also
- * flushed.
+ * Flushes this stream to ensure all pending data is written out to the
+ * target stream. In addition, the target stream is flushed.
*
* @throws IOException
- * If an error occurs attempting to flush this
- * BufferedOutputStream.
+ * if an error occurs attempting to flush this stream.
*/
@Override
public synchronized void flush() throws IOException {
@@ -89,25 +93,27 @@
}
/**
- * Writes <code>count</code> <code>bytes</code> from the byte array
- * <code>buffer</code> starting at <code>offset</code> to this
- * BufferedOutputStream. If there is room in the buffer to hold the bytes,
- * they are copied in. If not, the buffered bytes plus the bytes in
- * <code>buffer</code> are written to the target stream, the target is
- * flushed, and the buffer is cleared.
+ * Writes {@code count} bytes from the byte array {@code buffer} starting at
+ * {@code offset} to this stream. If there is room in the buffer to hold the
+ * bytes, they are copied in. If not, the buffered bytes plus the bytes in
+ * {@code buffer} are written to the target stream, the target is flushed,
+ * and the buffer is cleared.
*
* @param buffer
- * the buffer to be written
+ * the buffer to be written.
* @param offset
- * offset in buffer to get bytes
+ * the start position in {@code buffer} from where to get bytes.
* @param length
- * number of bytes in buffer to write
- *
+ * the number of bytes from {@code buffer} to write to this
+ * stream.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code length < 0}, or if
+ * {@code offset + length} is greater than the size of
+ * {@code buffer}.
* @throws IOException
- * If an error occurs attempting to write to this
- * BufferedOutputStream.
+ * if an error occurs attempting to write to this stream.
* @throws NullPointerException
- * If buffer is null.
+ * if {@code buffer} is {@code null}.
* @throws ArrayIndexOutOfBoundsException
* If offset or count is outside of bounds.
*/
@@ -141,19 +147,16 @@
}
/**
- * Writes the specified byte <code>oneByte</code> to this
- * BufferedOutputStream. Only the low order byte of <code>oneByte</code>
- * is written. If there is room in the buffer, the byte is copied in and the
- * count incremented. Otherwise, the buffer plus <code>oneByte</code> are
- * written to the target stream, the target is flushed, and the buffer is
- * reset.
+ * Writes one byte to this stream. Only the low order byte of the integer
+ * {@code oneByte} is written. If there is room in the buffer, the byte is
+ * copied into the buffer and the count incremented. Otherwise, the buffer
+ * plus {@code oneByte} are written to the target stream, the target is
+ * flushed, and the buffer is reset.
*
* @param oneByte
- * the byte to be written
- *
+ * the byte to be written.
* @throws IOException
- * If an error occurs attempting to write to this
- * BufferedOutputStream.
+ * if an error occurs attempting to write to this stream.
*/
@Override
public synchronized void write(int oneByte) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java Fri May 1 08:08:59 2009
@@ -20,20 +20,19 @@
import org.apache.harmony.luni.util.Msg;
/**
- * BufferedReader is a buffered character input reader. Buffering allows reading
- * from character streams more efficiently. If the default size of the buffer is
- * not practical, another size may be specified. Reading a character from a
- * Reader class usually involves reading a character from its Stream or
- * subsequent Reader. It is advisable to wrap a BufferedReader around those
- * Readers whose read operations may have high latency. For example, the
- * following code
+ * Wraps an existing {@link Reader} and <em>buffers</em> the input. Expensive
+ * interaction with the underlying reader is minimized, since most (smaller)
+ * requests can be satisfied by accessing the buffer alone. The drawback is that
+ * some extra space is required to hold the buffer and that copying takes place
+ * when filling that buffer, but this is usually outweighed by the performance
+ * benefits.
*
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
* <pre>
- * BufferedReader inReader = new BufferedReader(new FileReader("file.java"));
+ * BufferedReader buf = new BufferedReader(new FileReader("file.java"));
* </pre>
*
- * will buffer input for the file <code>file.java</code>.
- *
* @see BufferedWriter
* @since 1.1
*/
@@ -52,12 +51,11 @@
private int pos;
/**
- * Constructs a new BufferedReader on the Reader <code>in</code>. The
- * default buffer size (8K) is allocated and all reads can now be filtered
- * through this BufferedReader.
+ * Constructs a new BufferedReader on the Reader {@code in}. The
+ * buffer gets the default size (8 KB).
*
* @param in
- * the Reader to buffer reads on.
+ * the Reader that is buffered.
*/
public BufferedReader(Reader in) {
super(in);
@@ -66,16 +64,15 @@
}
/**
- * Constructs a new BufferedReader on the Reader <code>in</code>. The
- * buffer size is specified by the parameter <code>size</code> and all
- * reads can now be filtered through this BufferedReader.
+ * Constructs a new BufferedReader on the Reader {@code in}. The buffer
+ * size is specified by the parameter {@code size}.
*
* @param in
- * the Reader to buffer reads on.
+ * the Reader that is buffered.
* @param size
- * the size of buffer to allocate.
+ * the size of the buffer to allocate.
* @throws IllegalArgumentException
- * if the size is <= 0
+ * if {@code size <= 0}.
*/
public BufferedReader(Reader in, int size) {
super(in);
@@ -87,12 +84,12 @@
}
/**
- * Close the Reader. This implementation closes the Reader being filtered
- * and releases the buffer used by this reader. If this BufferedReader has
- * already been closed, nothing is done.
+ * Closes this reader. This implementation closes the buffered source reader
+ * and releases the buffer. Nothing is done if this reader has already been
+ * closed.
*
* @throws IOException
- * If an error occurs attempting to close this BufferedReader.
+ * if an error occurs while closing this reader.
*/
@Override
public void close() throws IOException {
@@ -137,30 +134,30 @@
}
/**
- * Answer a boolean indicating whether or not this BufferedReader is closed.
+ * Indicates whether or not this reader is closed.
*
- * @return <code>true</code> if this reader is closed, <code>false</code>
- * otherwise
+ * @return {@code true} if this reader is closed, {@code false}
+ * otherwise.
*/
private boolean isClosed() {
return buf == null;
}
/**
- * Set a Mark position in this BufferedReader. 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.
*
* @param readlimit
- * an int representing how many characters must be read before
- * invalidating the mark.
- *
- * @throws IOException
- * If an error occurs attempting mark this BufferedReader.
+ * the number of characters that can be read before the mark is
+ * invalidated.
* @throws IllegalArgumentException
- * If readlimit is < 0
+ * if {@code readlimit < 0}.
+ * @throws IOException
+ * if an error occurs while setting a mark in this reader.
+ * @see #markSupported()
+ * @see #reset()
*/
@Override
public void mark(int readlimit) throws IOException {
@@ -177,11 +174,12 @@
}
/**
- * Answers a boolean indicating whether or not this Reader supports mark()
- * and reset(). This implementation answers <code>true</code>.
+ * Indicates whether this reader supports the {@code mark()} and
+ * {@code reset()} methods. This implementation returns {@code true}.
*
- * @return <code>true</code> if mark() and reset() are supported,
- * <code>false</code> otherwise
+ * @return {@code true} for {@code BufferedReader}.
+ * @see #mark(int)
+ * @see #reset()
*/
@Override
public boolean markSupported() {
@@ -189,17 +187,16 @@
}
/**
- * 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. This implementation either returns a
- * character from the buffer or if there are no characters available, fill
- * the buffer then return a character or -1.
- *
- * @return the character read or -1 if end of reader.
- *
+ * Reads a single character from this reader and returns it with the two
+ * higher-order bytes set to 0. If possible, BufferedReader returns a
+ * character from the buffer. If there are no characters available in the
+ * buffer, it fills the buffer and then returns a character. It returns -1
+ * if there are no more characters in the source reader.
+ *
+ * @return the character read or -1 if the end of the source reader has been
+ * reached.
* @throws IOException
- * If the BufferedReader is already closed or some other IO
- * error occurs.
+ * if this reader is closed or some other I/O error occurs.
*/
@Override
public int read() throws IOException {
@@ -217,26 +214,30 @@
}
/**
- * Reads at most <code>length</code> characters from this BufferedReader
- * and stores them at <code>offset</code> in the character array
- * <code>buffer</code>. Returns the number of characters actually read or
- * -1 if the end of reader was encountered. If all the buffered characters
- * have been used, a mark has not been set, and the requested number of
- * characters is larger than this Readers buffer size, this implementation
- * bypasses the buffer and simply places the results directly into
- * <code>buffer</code>.
+ * Reads at most {@code length} characters from this reader and stores them
+ * at {@code offset} in the character array {@code buffer}. Returns the
+ * number of characters actually read or -1 if the end of the source reader
+ * has been reached. If all the buffered characters have been used, a mark
+ * has not been set and the requested number of characters is larger than
+ * this readers buffer size, BufferedReader bypasses the buffer and simply
+ * places the results directly into {@code buffer}.
*
* @param buffer
- * 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 bytes read
+ * from this reader.
* @param length
- * maximum number of characters to read
- * @return number of characters read or -1 if end of reader.
- *
+ * the maximum number of characters to read, must be
+ * non-negative.
+ * @return number of characters read or -1 if the end of the source reader
+ * has been reached.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code length < 0}, or if
+ * {@code offset + length} is greater than the size of
+ * {@code buffer}.
* @throws IOException
- * If the BufferedReader is already closed or some other IO
- * error occurs.
+ * if this reader is closed or some other I/O error occurs.
*/
@Override
public int read(char[] buffer, int offset, int length) throws IOException {
@@ -297,20 +298,16 @@
}
/**
- * 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>'\r\n'</code> or end of stream. The <code>String</code> does not
- * include the newline sequence.
- * In EBCDIC systems, a new line can also be represented by the
- * <code>'\u0085'</code> (NEL) character.
- *
- * @return the contents of the line or null if no characters were read
- * before end of stream.
+ * Returns the next line of text available from this reader. A line is
+ * represented by zero or more characters followed by {@code '\n'},
+ * {@code '\r'}, {@code "\r\n"} or the end of the reader. The string does
+ * not include the newline sequence. In EBCDIC systems, a new line can also
+ * be represented by the {@code \u0085} (NEL) character.
*
+ * @return the contents of the line or {@code null} if no characters were
+ * read before the end of the reader has been reached.
* @throws IOException
- * If the BufferedReader is already closed or some other IO
- * error occurs.
+ * if this reader is closed or some other I/O error occurs.
*/
public String readLine() throws IOException {
synchronized (lock) {
@@ -396,19 +393,15 @@
}
/**
- * 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.
+ * Indicates whether this reader is ready to be read without blocking.
*
+ * @return {@code true} if this reader will not block when {@code read} is
+ * called, {@code false} if unknown or blocking will occur.
* @throws IOException
- * If the BufferedReader is already closed or some other IO
- * error occurs.
+ * if this reader is closed or some other I/O error occurs.
+ * @see #read()
+ * @see #read(char[], int, int)
+ * @see #readLine()
*/
@Override
public boolean ready() throws IOException {
@@ -421,13 +414,14 @@
}
/**
- * Reset this BufferedReader's 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, throw IOException.
+ * Resets this reader's position to the last {@code mark()} location.
+ * Invocations of {@code read()} and {@code skip()} will occur from this new
+ * location.
*
* @throws IOException
- * If a problem occurred, the receiver does not support
- * <code>mark()/reset()</code>, or no mark has been set.
+ * if this reader is closed or no mark has been set.
+ * @see #mark(int)
+ * @see #markSupported()
*/
@Override
public void reset() throws IOException {
@@ -443,20 +437,21 @@
}
/**
- * Skips <code>amount</code> number of characters in this Reader.
- * Subsequent <code>read()</code>'s will not return these characters
- * unless <code>reset()</code> is used. Skipping characters may invalidate
- * a mark if marklimit is surpassed.
+ * Skips {@code amount} characters in this reader. Subsequent
+ * {@code read()}s will not return these characters unless {@code reset()}
+ * is used. Skipping characters may invalidate a mark if {@code readlimit}
+ * is surpassed.
*
* @param amount
* the maximum number of characters to skip.
* @return the number of characters actually skipped.
- *
- * @throws IOException
- * If the BufferedReader is already closed or some other IO
- * error occurs.
* @throws IllegalArgumentException
- * If amount is negative
+ * 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()
*/
@Override
public long skip(long amount) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java Fri May 1 08:08:59 2009
@@ -23,10 +23,19 @@
import org.apache.harmony.luni.util.PriviAction;
/**
- * BufferedWriter is for writing buffered character output. Characters written
- * to this Writer are buffered internally before being committed to the target
- * Writer.
+ * Wraps an existing {@link Writer} and <em>buffers</em> the output. Expensive
+ * interaction with the underlying reader is minimized, since most (smaller)
+ * requests can be satisfied by accessing the buffer alone. The drawback is that
+ * some extra space is required to hold the buffer and that copying takes place
+ * when filling that buffer, but this is usually outweighed by the performance
+ * benefits.
*
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
+ * <pre>
+ * BufferedWriter buf = new BufferedWriter(new FileWriter("file.java"));
+ * </pre>
+ *
* @see BufferedReader
*/
public class BufferedWriter extends Writer {
@@ -41,12 +50,12 @@
.doPrivileged(new PriviAction<String>("line.separator")); //$NON-NLS-1$
/**
- * Constructs a new BufferedReader with <code>out</code> as the Writer on
- * which to buffer write operations. The buffer size is set to the default,
- * which is 8K.
+ * Constructs a new {@code BufferedWriter} with {@code out} as the writer
+ * for which to buffer write operations. The buffer size is set to the
+ * default value of 8 KB.
*
* @param out
- * The Writer to buffer character writing on
+ * the writer for which character writing is buffered.
*/
public BufferedWriter(Writer out) {
super(out);
@@ -55,14 +64,16 @@
}
/**
- * Constructs a new BufferedReader with <code>out</code> as the Writer on
- * which buffer write operations. The buffer size is set to
- * <code>size</code>.
+ * Constructs a new {@code BufferedWriter} with {@code out} as the writer
+ * for which to buffer write operations. The buffer size is set to {@code
+ * size}.
*
* @param out
- * The Writer to buffer character writing on.
+ * the writer for which character writing is buffered.
* @param size
- * The size of the buffer to use.
+ * the size of the buffer in bytes.
+ * @throws IllegalArgumentException
+ * if {@code size <= 0}.
*/
public BufferedWriter(Writer out, int size) {
super(out);
@@ -74,12 +85,12 @@
}
/**
- * Close this BufferedWriter. The contents of the buffer are flushed, the
- * target writer is closed, and the buffer is released. Only the first
- * invocation of close has any effect.
+ * Closes this writer. The contents of the buffer are flushed, the target
+ * writer is closed, and the buffer is released. Only the first invocation
+ * of close has any effect.
*
* @throws IOException
- * If an error occurs attempting to close this Writer.
+ * if an error occurs while closing this writer.
*/
@Override
public void close() throws IOException {
@@ -94,11 +105,11 @@
}
/**
- * Flush this BufferedWriter. The contents of the buffer are committed to
- * the target writer and it is then flushed.
+ * Flushes this writer. The contents of the buffer are committed to the
+ * target writer and it is then flushed.
*
* @throws IOException
- * If an error occurs attempting to flush this Writer.
+ * if an error occurs while flushing this writer.
*/
@Override
public void flush() throws IOException {
@@ -122,45 +133,44 @@
}
/**
- * Answer a boolean indicating whether or not this BufferedWriter is closed.
+ * Indicates whether this writer is closed.
*
- * @return <code>true</code> if this reader is closed, <code>false</code>
- * otherwise
+ * @return {@code true} if this writer is closed, {@code false} otherwise.
*/
private boolean isClosed() {
return out == null;
}
/**
- * Write a newline to thie Writer. A newline is determined by the System
+ * Writes a newline to this writer. A newline is determined by the System
* property "line.separator". The target writer may or may not be flushed
* when a newline is written.
*
* @throws IOException
- * If an error occurs attempting to write to this Writer.
+ * if an error occurs attempting to write to this writer.
*/
public void newLine() throws IOException {
write(lineSeparator, 0, lineSeparator.length());
}
/**
- * Writes out <code>count</code> characters starting at
- * <code>offset</code> in <code>buf</code> to this BufferedWriter. If
- * <code>count</code> is greater than this Writers buffer then flush the
- * contents and also write the characters directly to the target Writer.
+ * Writes {@code count} characters starting at {@code offset} in
+ * {@code cbuf} to this writer. If {@code count} is greater than this
+ * writer's buffer, then the buffer is flushed and the characters are
+ * written directly to the target writer.
*
* @param cbuf
- * the non-null array containing characters to write.
+ * the array containing characters to write.
* @param offset
- * offset in buf to retrieve characters
+ * the start position in {@code cbuf} for retrieving characters.
* @param count
- * maximum number of characters to write
- *
- * @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
+ * the maximum number of characters to write.
* @throws IndexOutOfBoundsException
- * If offset or count are outside of bounds.
+ * if {@code offset < 0} or {@code count < 0}, or if
+ * {@code offset + count} is greater than the size of
+ * {@code cbuf}.
+ * @throws IOException
+ * if this writer is closed or another I/O error occurs.
*/
@Override
public void write(char[] cbuf, int offset, int count) throws IOException {
@@ -202,16 +212,14 @@
}
/**
- * Writes the character <code>oneChar</code> BufferedWriter. If the buffer
- * is filled by writing this character, flush this Writer. Only the lower 2
- * bytes are written.
+ * Writes the character {@code oneChar} to this writer. If the buffer
+ * gets full by writing this character, this writer is flushed. Only the
+ * lower two bytes of the integer {@code oneChar} are written.
*
* @param oneChar
- * The Character to write out.
- *
+ * the character to write.
* @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
+ * if this writer is closed or another I/O error occurs.
*/
@Override
public void write(int oneChar) throws IOException {
@@ -228,23 +236,24 @@
}
/**
- * Writes out <code>count</code> characters starting at
- * <code>offset</code> in <code>str</code> to this BufferedWriter. If
- * <code>count</code> is greater than this Writers buffer then flush the
- * contents and also write the characters directly to the target Writer.
+ * Writes {@code count} characters starting at {@code offset} in {@code str}
+ * to this writer. If {@code count} is greater than this writer's buffer,
+ * then this writer is flushed and the remaining characters are written
+ * directly to the target writer. If count is negative no characters are
+ * written to the buffer. This differs from the behavior of the superclass.
*
* @param str
- * the non-null String containing characters to write
+ * the non-null String containing characters to write.
* @param offset
- * offset in str to retrieve characters
+ * the start position in {@code str} for retrieving characters.
* @param count
- * maximum number of characters to write
- *
+ * maximum number of characters to write.
* @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
- * @throws ArrayIndexOutOfBoundsException
- * If offset or count are outside of bounds.
+ * if this writer has already been closed or another I/O error
+ * occurs.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code offset + count} is greater
+ * than the length of {@code str}.
*/
@Override
public void write(String str, int offset, int count) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java Fri May 1 08:08:59 2009
@@ -18,13 +18,13 @@
package java.io;
/**
- * ByteArrayInputStream is used for streaming over a byte array.
+ * A specialized {@link InputStream } for reading the contents of a byte array.
*
* @see ByteArrayOutputStream
*/
public class ByteArrayInputStream extends InputStream {
/**
- * The <code>byte</code> array containing the bytes to stream over.
+ * The {@code byte} array containing the bytes to stream over.
*/
protected byte[] buf;
@@ -41,15 +41,16 @@
/**
* The total number of bytes initially available in the byte array
- * <code>buf</code>.
+ * {@code buf}.
*/
protected int count;
/**
- * Constructs a new ByteArrayInputStream on the byte array <code>buf</code>.
+ * Constructs a new {@code ByteArrayInputStream} on the byte array
+ * {@code buf}.
*
* @param buf
- * the byte array to stream over
+ * the byte array to stream over.
*/
public ByteArrayInputStream(byte buf[]) {
this.mark = 0;
@@ -58,16 +59,16 @@
}
/**
- * Constructs a new ByteArrayInputStream on the byte array <code>buf</code>
- * with the position set to <code>offset</code> and the number of bytes
- * available set to <code>offset</code> + <code>length</code>.
+ * Constructs a new {@code ByteArrayInputStream} on the byte array
+ * {@code buf} with the initial position set to {@code offset} and the
+ * number of bytes available set to {@code offset} + {@code length}.
*
* @param buf
- * the byte array to stream over
+ * the byte array to stream over.
* @param offset
- * the offset in <code>buf</code> to start streaming at
+ * the initial position in {@code buf} to start streaming from.
* @param length
- * the number of bytes available to stream over.
+ * the number of bytes available for streaming.
*/
public ByteArrayInputStream(byte buf[], int offset, int length) {
this.buf = buf;
@@ -77,9 +78,9 @@
}
/**
- * Answers a int representing then number of bytes that are available before
- * this ByteArrayInputStream will block. This method returns the number of
- * bytes yet to be read from the underlying byte array.
+ * Returns the number of bytes that are available before this stream will
+ * block. This method returns the number of bytes yet to be read from the
+ * source byte array.
*
* @return the number of bytes available before blocking.
*/
@@ -89,11 +90,10 @@
}
/**
- * Close the ByteArrayInputStream. This implementation frees up resources
- * associated with this stream.
+ * Closes this stream and frees resources associated with this stream.
*
* @throws IOException
- * If an error occurs attempting to close this InputStream.
+ * if an I/O error occurs while closing this stream.
*/
@Override
public void close() throws IOException {
@@ -101,12 +101,14 @@
}
/**
- * Set a Mark position in this ByteArrayInputStream. The parameter
- * <code>readLimit</code> is ignored. Sending reset() will reposition the
+ * Sets a mark position in this ByteArrayInputStream. The parameter
+ * {@code readlimit} is ignored. Sending {@code reset()} will reposition the
* stream back to the marked position.
*
* @param readlimit
* ignored.
+ * @see #markSupported()
+ * @see #reset()
*/
@Override
public synchronized void mark(int readlimit) {
@@ -114,13 +116,13 @@
}
/**
- * Answers a boolean indicating whether or not this ByteArrayInputStream
- * supports mark() and reset(). This implementation answers
- * <code>true</code>.
- *
- * @return <code>true</code> indicates this stream supports mark/reset,
- * <code>false
- * <code> otherwise.
+ * Indicates whether this stream supports the {@code mark()} and
+ * {@code reset()} methods. Returns {@code true} since this class supports
+ * these methods.
+ *
+ * @return always {@code true}.
+ * @see #mark(int)
+ * @see #reset()
*/
@Override
public boolean markSupported() {
@@ -128,12 +130,11 @@
}
/**
- * Reads a single byte from this ByteArrayInputStream and returns the result
- * as an int. The low-order byte is returned or -1 of the end of stream was
- * encountered. This implementation returns the next available byte from the
- * target byte array.
+ * Reads a single byte from the source byte array and returns it as an
+ * integer in the range from 0 to 255. Returns -1 if the end of the source
+ * array has been reached.
*
- * @return the byte read or -1 if end of stream.
+ * @return the byte read or -1 if the end of this stream has been reached.
*/
@Override
public synchronized int read() {
@@ -141,19 +142,25 @@
}
/**
- * Reads at most <code>len</code> bytes from this ByteArrayInputStream and
- * stores them in byte array <code>b</code> starting at offset
- * <code>off</code>. Answer the number of bytes actually read or -1 if no
- * bytes were read and end of stream was encountered. This implementation
- * reads bytes from the target byte array.
+ * Reads at most {@code len} bytes from this stream and stores
+ * them in byte array {@code b} starting at {@code offset}. This
+ * implementation reads bytes from the source byte array.
*
* @param b
- * the byte array in which to store the read bytes.
+ * the byte array in which to store the bytes read.
* @param offset
- * the offset in <code>b</code> to store the read bytes.
+ * the initial position in {@code b} to store the bytes read from
+ * this stream.
* @param length
- * the maximum number of bytes to store in <code>b</code>.
- * @return the number of bytes actually read or -1 if end of stream.
+ * the maximum number of bytes to store in {@code b}.
+ * @return the number of bytes actually read or -1 if no bytes were read and
+ * the end of the stream was encountered.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code length < 0}, or if
+ * {@code offset + length} is greater than the size of
+ * {@code b}.
+ * @throws NullPointerException
+ * if {@code b} is null.
*/
@Override
public synchronized int read(byte b[], int offset, int length) {
@@ -180,10 +187,11 @@
}
/**
- * Reset this ByteArrayInputStream to the last marked location. This
- * implementation resets the position to either the marked position, the
- * start position supplied in the constructor or <code>0</code> if neither
- * is provided.
+ * Resets this stream to the last marked location. This implementation
+ * resets the position to either the marked position, the start position
+ * supplied in the constructor or 0 if neither has been provided.
+ *
+ * @see #mark(int)
*/
@Override
public synchronized void reset() {
@@ -191,10 +199,10 @@
}
/**
- * Skips <code>count</code> number of bytes in this InputStream.
- * Subsequent <code>read()</code>'s will not return these bytes unless
- * <code>reset()</code> is used. This implementation skips
- * <code>count</code> number of bytes in the target stream.
+ * Skips {@code count} number of bytes in this InputStream. Subsequent
+ * {@code read()}s will not return these bytes unless {@code reset()} is
+ * used. This implementation skips {@code count} number of bytes in the
+ * target stream. It does nothing and returns 0 if {@code n} is negative.
*
* @param n
* the number of bytes to skip.
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java Fri May 1 08:08:59 2009
@@ -20,9 +20,10 @@
import org.apache.harmony.luni.util.Msg;
/**
- * ByteArrayOutputStream is a class whose underlying stream is represented by a
- * byte array. As bytes are written to this stream, the local byte array may be
- * expanded to hold more bytes.
+ * A specialized {@link OutputStream} for class for writing content to an
+ * (internal) byte array. As bytes are written to this stream, the byte array
+ * may be expanded to hold more bytes. When the writing is considered to be
+ * finished, a copy of the byte array can be requested from the class.
*
* @see ByteArrayInputStream
*/
@@ -40,8 +41,7 @@
/**
* Constructs a new ByteArrayOutputStream with a default size of 32 bytes.
* If more than 32 bytes are written to this instance, the underlying byte
- * array will expand to accommodate.
- *
+ * array will expand.
*/
public ByteArrayOutputStream() {
super();
@@ -49,14 +49,15 @@
}
/**
- * Constructs a new ByteArrayOutputStream with a default size of
- * <code>size</code> bytes. If more than <code>size</code> bytes are
- * written to this instance, the underlying byte array will expand to
- * accommodate.
+ * Constructs a new {@code ByteArrayOutputStream} with a default size of
+ * {@code size} bytes. If more than {@code size} bytes are written to this
+ * instance, the underlying byte array will expand.
*
* @param size
- * an non-negative integer representing the initial size for the
- * underlying byte array.
+ * initial size for the underlying byte array, must be
+ * non-negative.
+ * @throws IllegalArgumentException
+ * if {@code size} < 0.
*/
public ByteArrayOutputStream(int size) {
super();
@@ -68,11 +69,10 @@
}
/**
- * Close this ByteArrayOutputStream. This implementation releases System
- * resources used for this stream.
+ * Closes this stream. This releases system resources used for this stream.
*
* @throws IOException
- * If an error occurs attempting to close this OutputStream.
+ * if an error occurs while attempting to close this stream.
*/
@Override
public void close() throws IOException {
@@ -96,30 +96,29 @@
}
/**
- * Reset this ByteArrayOutputStream to the beginning of the underlying byte
- * array. All subsequent writes will overwrite any bytes previously stored
- * in this stream.
- *
+ * Resets this stream to the beginning of the underlying byte array. All
+ * subsequent writes will overwrite any bytes previously stored in this
+ * stream.
*/
public synchronized void reset() {
count = 0;
}
/**
- * Answers the total number of bytes written to this stream thus far.
+ * Returns the total number of bytes written to this stream so far.
*
- * @return the number of bytes written to this Stream.
+ * @return the number of bytes written to this stream.
*/
public int size() {
return count;
}
/**
- * Answer the contents of this ByteArrayOutputStream as a byte array. Any
+ * Returns the contents of this ByteArrayOutputStream as a byte array. Any
* changes made to the receiver after returning will not be reflected in the
* byte array returned to the caller.
*
- * @return this streams current contents as a byte array.
+ * @return this stream's current contents as a byte array.
*/
public synchronized byte[] toByteArray() {
byte[] newArray = new byte[count];
@@ -128,11 +127,11 @@
}
/**
- * Answer the contents of this ByteArrayOutputStream as a String. Any
+ * Returns the contents of this ByteArrayOutputStream as a string. Any
* changes made to the receiver after returning will not be reflected in the
- * String returned to the caller.
+ * string returned to the caller.
*
- * @return this streams current contents as a String.
+ * @return this stream's current contents as a string.
*/
@Override
@@ -141,19 +140,18 @@
}
/**
- * Answer the contents of this ByteArrayOutputStream as a String. Each byte
- * <code>b</code> in this stream is converted to a character
- * <code>c</code> using the following function:
- * <code>c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))</code>. This
- * method is deprecated and either toString(), or toString(enc) should be
- * used.
+ * Returns the contents of this ByteArrayOutputStream as a string. Each byte
+ * {@code b} in this stream is converted to a character {@code c} using the
+ * following function:
+ * {@code c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))}. This method is
+ * deprecated and either {@link #toString()} or {@link #toString(String)}
+ * should be used.
*
* @param hibyte
- * the high byte of each resulting Unicode character
- * @return this streams current contents as a String with the high byte set
- * to <code>hibyte</code>
- *
- * @deprecated Use toString()
+ * the high byte of each resulting Unicode character.
+ * @return this stream's current contents as a string with the high byte set
+ * to {@code hibyte}.
+ * @deprecated Use {@link #toString()}.
*/
@Deprecated
public String toString(int hibyte) {
@@ -165,37 +163,36 @@
}
/**
- * Answer the contents of this ByteArrayOutputStream as a String converted
- * using the encoding declared in <code>enc</code>.
+ * Returns the contents of this ByteArrayOutputStream as a string converted
+ * according to the encoding declared in {@code enc}.
*
* @param enc
- * A String representing the encoding to use when translating
- * this stream to a String.
- * @return this streams current contents as a String.
- *
+ * a string representing the encoding to use when translating
+ * this stream to a string.
+ * @return this stream's current contents as an encoded string.
* @throws UnsupportedEncodingException
- * If declared encoding is not supported
+ * if the provided encoding is not supported.
*/
public String toString(String enc) throws UnsupportedEncodingException {
return new String(buf, 0, count, enc);
}
/**
- * Writes <code>count</code> <code>bytes</code> from the byte array
- * <code>buffer</code> starting at offset <code>index</code> to the
- * ByteArrayOutputStream.
+ * Writes {@code count} bytes from the byte array {@code buffer} starting at
+ * offset {@code index} to this stream.
*
* @param buffer
- * the buffer to be written
+ * the buffer to be written.
* @param offset
- * offset in buffer to get bytes
+ * the initial position in {@code buffer} to retrieve bytes.
* @param len
- * number of bytes in buffer to write
- *
+ * the number of bytes of {@code buffer} to write.
* @throws NullPointerException
* If buffer is null.
* @throws IndexOutOfBoundsException
- * If offset or count are outside of bounds.
+ * if {@code offset < 0} or {@code len < 0}, or if
+ * {@code offset + len} is greater than the length of
+ * {@code buffer}.
*/
@Override
public synchronized void write(byte[] buffer, int offset, int len) {
@@ -215,11 +212,11 @@
}
/**
- * Writes the specified byte <code>oneByte</code> to the OutputStream.
- * Only the low order byte of <code>oneByte</code> is written.
+ * Writes the specified byte {@code oneByte} to the OutputStream. Only the
+ * low order byte of {@code oneByte} is written.
*
* @param oneByte
- * the byte to be written
+ * the byte to be written.
*/
@Override
public synchronized void write(int oneByte) {
@@ -230,14 +227,13 @@
}
/**
- * Take the contents of this stream and write it to the output stream
- * <code>out</code>.
+ * Takes the contents of this stream and writes it to the output stream
+ * {@code out}.
*
* @param out
- * An OutputStream on which to write the contents of this stream.
- *
+ * an OutputStream on which to write the contents of this stream.
* @throws IOException
- * If an error occurs when writing to output stream
+ * if an error occurs while writing to {@code out}.
*/
public synchronized void writeTo(OutputStream out) throws IOException {
out.write(buf, 0, count);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java Fri May 1 08:08:59 2009
@@ -20,22 +20,23 @@
import org.apache.harmony.luni.util.Msg;
/**
- * CharArrayReader is used as a buffered character input stream on a character
- * array.
+ * A specialized {@link Reader} for reading the contents of a char array.
+ *
+ * @see CharArrayWriter
*/
public class CharArrayReader extends Reader {
/**
- * Buffer for characters
+ * The buffer for characters.
*/
protected char buf[];
/**
- * Current buffer position.
+ * The current buffer position.
*/
protected int pos;
/**
- * Current mark position.
+ * The current mark position.
*/
protected int markedPos = -1;
@@ -45,13 +46,12 @@
protected int count;
/**
- * Construct a CharArrayReader on the char array <code>buffer</code>. The
- * size of the reader is set to the <code>length()</code> of the buffer
- * and the Object to synchronize access through is set to
- * <code>buffer</code>.
+ * Constructs a CharArrayReader on the char array {@code buf}. The size of
+ * the reader is set to the length of the buffer and the object to to read
+ * from is set to {@code buf}.
*
* @param buf
- * the char array to filter reads on.
+ * the char array from which to read.
*/
public CharArrayReader(char[] buf) {
super(buf);
@@ -60,18 +60,20 @@
}
/**
- * Construct a CharArrayReader on the char array <code>buffer</code>. The
- * size of the reader is set to the parameter <code>length()</code> and
- * the original offset is set to <code>offset</code>.
+ * Constructs a CharArrayReader on the char array {@code buf}. The size of
+ * the reader is set to {@code length} and the start position from which to
+ * read the buffer is set to {@code offset}.
*
* @param buf
- * the char array to filter reads on.
+ * the char array from which to read.
* @param offset
- * the offset in <code>buf</code> to start streaming at.
+ * the index of the first character in {@code buf} to read.
* @param length
- * the number of characters available to stream over.
+ * the number of characters that can be read from {@code buf}.
+ * @throws IllegalArgumentException
+ * if {@code offset < 0} or {@code length < 0}, or if
+ * {@code offset} is greater than the size of {@code buf} .
*/
-
public CharArrayReader(char[] buf, int offset, int length) {
super(buf);
if (offset < 0 || offset > buf.length || length < 0) {
@@ -100,37 +102,33 @@
}
/**
- * Answer a boolean indicating whether or not this CharArrayReader is open.
+ * Indicates whether this reader is open.
*
- * @return <code>true</code> if the reader is open, <code>false</code>
- * otherwise.
+ * @return {@code true} if the reader is open, {@code false} otherwise.
*/
private boolean isOpen() {
return buf != null;
}
/**
- * Answer a boolean indicating whether or not this CharArrayReader is
- * closed.
+ * Indicates whether this reader is closed.
*
- * @return <code>true</code> if the reader is closed, <code>false</code>
- * otherwise.
+ * @return {@code true} if the reader is closed, {@code false} otherwise.
*/
private boolean isClosed() {
return buf == null;
}
/**
- * Set a Mark position in this Reader. The parameter <code>readLimit</code>
- * is ignored for CharArrayReaders. Sending reset() will reposition the
+ * Sets a mark position in this reader. The parameter {@code readLimit} is
+ * ignored for CharArrayReaders. Calling {@code reset()} will reposition the
* reader back to the marked position provided the mark has not been
* invalidated.
*
* @param readLimit
* ignored for CharArrayReaders.
- *
* @throws IOException
- * If an error occurs attempting to mark this CharArrayReader.
+ * if this reader is closed.
*/
@Override
public void mark(int readLimit) throws IOException {
@@ -143,10 +141,12 @@
}
/**
- * Answers a boolean indicating whether or not this CharArrayReader supports
- * mark() and reset(). This method always returns true.
+ * Indicates whether this reader supports the {@code mark()} and
+ * {@code reset()} methods.
*
- * @return indicates whether or not mark() and reset() are supported.
+ * @return {@code true} for CharArrayReader.
+ * @see #mark(int)
+ * @see #reset()
*/
@Override
public boolean markSupported() {
@@ -154,14 +154,14 @@
}
/**
- * Reads a single character from this CharArrayReader and returns the result
- * as an int. The 2 higher-order bytes are set to 0. If the end of reader
- * was encountered then return -1.
- *
- * @return int 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 no more
+ * characters are available from this reader.
+ *
+ * @return the character read as an int or -1 if the end of the reader has
+ * been reached.
* @throws IOException
- * If the CharArrayReader is already closed.
+ * if this reader is closed.
*/
@Override
public int read() throws IOException {
@@ -177,22 +177,26 @@
}
/**
- * Reads at most <code>count</code> characters from this CharArrayReader
- * 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 CharArrayReader 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 reader
+ * was encountered.
*
* @param buffer
- * 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 len
- * maximum number of characters to read
- * @return number of characters read or -1 if end of reader.
- *
+ * the maximum number of characters to read.
+ * @return number of characters read or -1 if the end of the reader has been
+ * reached.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code len < 0}, or if
+ * {@code offset + len} is bigger than the size of
+ * {@code buffer}.
* @throws IOException
- * If the CharArrayReader is closed.
+ * if this reader is closed.
*/
@Override
public int read(char buffer[], int offset, int len) throws IOException {
@@ -216,19 +220,16 @@
}
/**
- * Answers a <code>boolean</code> indicating whether or not this
- * CharArrayReader 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. The implementation in CharArrayReader
- * always returns <code>true</code> even when it has been closed.
- *
- * @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.
+ * Indicates whether this reader is ready to be read without blocking.
+ * Returns {@code true} if the next {@code read} will not block. Returns
+ * {@code false} if this reader may or may not block when {@code read} is
+ * called. The implementation in CharArrayReader always returns {@code true}
+ * even when it has been closed.
*
+ * @return {@code true} if this reader will not block when {@code read} is
+ * called, {@code false} if unknown or blocking will occur.
* @throws IOException
- * If the CharArrayReader is closed.
+ * if this reader is closed.
*/
@Override
public boolean ready() throws IOException {
@@ -241,13 +242,13 @@
}
/**
- * Reset this CharArrayReader's 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 CharArrayReader is
- * reset to the beginning of the String.
+ * 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, it is reset to the
+ * beginning of the string.
*
* @throws IOException
- * If this CharArrayReader has already been closed.
+ * if this reader is closed.
*/
@Override
public void reset() throws IOException {
@@ -260,16 +261,15 @@
}
/**
- * Skips <code>count</code> number of characters in this CharArrayReader.
- * Subsequent <code>read()</code>'s will not return these characters
- * unless <code>reset()</code> is used.
+ * Skips {@code count} number of characters in this reader. Subsequent
+ * {@code read()}s will not return these characters unless {@code reset()}
+ * is used. This method does nothing and returns 0 if {@code n} is negative.
*
* @param n
- * The number of characters to skip.
- * @return long The number of characters actually skipped.
- *
+ * the number of characters to skip.
+ * @return the number of characters actually skipped.
* @throws IOException
- * If this CharArrayReader has already been closed.
+ * if this reader is closed.
*/
@Override
public long skip(long n) throws IOException {