Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 20269 invoked from network); 1 May 2009 08:09:39 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 1 May 2009 08:09:39 -0000 Received: (qmail 63354 invoked by uid 500); 1 May 2009 08:09:39 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 63293 invoked by uid 500); 1 May 2009 08:09:39 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 63284 invoked by uid 99); 1 May 2009 08:09:39 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:09:39 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:09:25 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 36CD02388B7B; Fri, 1 May 2009 08:09:04 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r770573 [1/10] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ Date: Fri, 01 May 2009 08:09:01 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090501080904.36CD02388B7B@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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; /** - * BufferedInputStream is a class which takes an input stream and - * buffers 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 buffers 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. * + *

A typical application pattern for the class looks like this:

+ * + * 

+ * BufferedInputStream buf = new BufferedInputStream(new FileInputStream("file.java"));
+ *
+ * * @see BufferedOutputStream */ public class BufferedInputStream extends FilterInputStream { @@ -35,7 +42,7 @@ protected volatile byte[] buf; /** - * The total number of bytes inside the byte array buf. + * 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 buf. + * The current position within the byte array {@code buf}. */ protected int pos; /** - * Constructs a new BufferedInputStream on the InputStream - * in. 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 in. - * The buffer size is specified by the parameter size 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 - * readLimit indicates how many bytes can be read before a mark - * is invalidated. Sending reset() will reposition the Stream back to the - * marked position provided readLimit has not been surpassed. - * The underlying buffer may be increased in size to allow - * readlimit 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 - * true. + * Indicates whether {@code BufferedInputStream} supports the {@code mark()} + * and {@code reset()} methods. * - * @return true 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 length bytes from this BufferedInputStream and - * stores them in byte array buffer starting at offset - * offset. Answer the number of bytes actually read or -1 if no - * bytes were read and end of stream was encountered. 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 - * buffer. + * 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 buffer 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 buffer. + * 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 - * readlimit has been passed or no mark 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 amount number of bytes in this BufferedInputStream. - * Subsequent read()'s will not return these bytes unless - * reset() 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 - * buffers 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 buffers 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. * + *

A typical application pattern for the class looks like this:

+ * + * 

+ * BufferedOutputStream buf = new BufferedOutputStream(new FileOutputStream("file.java"));
+ *
+ * * @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 buf. + * The total number of bytes inside the byte array {@code buf}. */ protected int count; /** - * Constructs a new BufferedOutputStream on the OutputStream - * out. 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 - * out. The buffer size is set to size 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 count bytes from the byte array - * buffer starting at offset 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 - * buffer 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 oneByte to this - * BufferedOutputStream. Only the low order byte of oneByte - * is written. If there is room in the buffer, the byte is copied in and the - * count incremented. Otherwise, the buffer plus oneByte 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 buffers 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. * + *

A typical application pattern for the class looks like this:

+ * * 

- * BufferedReader inReader = new BufferedReader(new FileReader("file.java"));
+ * BufferedReader buf = new BufferedReader(new FileReader("file.java"));
  *
* - * will buffer input for the file file.java. - * * @see BufferedWriter * @since 1.1 */ @@ -52,12 +51,11 @@ private int pos; /** - * Constructs a new BufferedReader on the Reader in. 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 in. The - * buffer size is specified by the parameter size 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 true if this reader is closed, false - * 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 - * readLimit indicates how many characters can be read before - * a mark is invalidated. Sending reset() will reposition the reader back to - * the marked position provided readLimit has not been - * surpassed. + * 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 true. + * Indicates whether this reader supports the {@code mark()} and + * {@code reset()} methods. This implementation returns {@code true}. * - * @return true if mark() and reset() are supported, - * false 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 length characters from this BufferedReader - * and stores them at offset in the character array - * buffer. 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 - * buffer. + * 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 String representing the next line of text - * available in this BufferedReader. A line is represented by 0 or more - * characters followed by '\n', '\r', - * '\r\n' or end of stream. The String does not - * include the newline sequence. - * In EBCDIC systems, a new line can also be represented by the - * '\u0085' (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 boolean indicating whether or not this Reader is - * ready to be read without blocking. If the result is true, - * the next read() will not block. If the result is - * false this Reader may or may not block when - * read() is sent. - * - * @return true if the receiver will not block when - * read() is called, false 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 mark() - * location. Invocations of read()/skip() 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 - * mark()/reset(), 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 amount number of characters in this Reader. - * Subsequent read()'s will not return these characters - * unless reset() 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 buffers 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. * + *

A typical application pattern for the class looks like this:

+ * + * 

+ * BufferedWriter buf = new BufferedWriter(new FileWriter("file.java"));
+ *
+ * * @see BufferedReader */ public class BufferedWriter extends Writer { @@ -41,12 +50,12 @@ .doPrivileged(new PriviAction("line.separator")); //$NON-NLS-1$ /** - * Constructs a new BufferedReader with out 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 out as the Writer on - * which buffer write operations. The buffer size is set to - * size. + * 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 true if this reader is closed, false - * 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 count characters starting at - * offset in buf to this BufferedWriter. If - * count 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 oneChar 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 count characters starting at - * offset in str to this BufferedWriter. If - * count 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 byte 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 - * buf. + * {@code buf}. */ protected int count; /** - * Constructs a new ByteArrayInputStream on the byte array buf. + * 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 buf - * with the position set to offset and the number of bytes - * available set to offset + length. + * 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 buf 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 - * readLimit 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 - * true. - * - * @return true indicates this stream supports mark/reset, - * false - * 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 len bytes from this ByteArrayInputStream and - * stores them in byte array b starting at offset - * off. 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 b 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 b. - * @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 0 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 count number of bytes in this InputStream. - * Subsequent read()'s will not return these bytes unless - * reset() is used. This implementation skips - * count 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 - * size bytes. If more than size 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 - * b in this stream is converted to a character - * c using the following function: - * c == (char)(((hibyte & 0xff) << 8) | (b & 0xff)). 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 hibyte - * - * @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 enc. + * 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 count bytes from the byte array - * buffer starting at offset index 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 oneByte to the OutputStream. - * Only the low order byte of oneByte 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 - * out. + * 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 buffer. The - * size of the reader is set to the length() of the buffer - * and the Object to synchronize access through is set to - * buffer. + * 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 buffer. The - * size of the reader is set to the parameter length() and - * the original offset is set to offset. + * 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 buf 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 true if the reader is open, false - * 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 true if the reader is closed, false - * 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 readLimit - * 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 count characters from this CharArrayReader - * and stores them at offset in the character array - * buf. 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 boolean indicating whether or not this - * CharArrayReader is ready to be read without blocking. If the result is - * true, the next read() will not block. If - * the result is false this Reader may or may not block when - * read() is sent. The implementation in CharArrayReader - * always returns true even when it has been closed. - * - * @return true if the receiver will not block when - * read() is called, false 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 mark() - * location. Invocations of read()/skip() 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 count number of characters in this CharArrayReader. - * Subsequent read()'s will not return these characters - * unless reset() 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 {