Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 20577 invoked from network); 1 May 2009 08:10:05 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 1 May 2009 08:10:05 -0000 Received: (qmail 64209 invoked by uid 500); 1 May 2009 08:10:05 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 64142 invoked by uid 500); 1 May 2009 08:10:05 -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 64133 invoked by uid 99); 1 May 2009 08:10:05 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:10:05 +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:59 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 7246F2388CFA; 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 [7/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.7246F2388CFA@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java Fri May 1 08:08:59 2009 @@ -30,15 +30,15 @@ import org.apache.harmony.luni.util.PriviAction; /** - * OutputStreamWriter is a class for turning a character output stream into a - * byte output stream. The conversion of Unicode characters to their byte - * equivalents is determined by the converter used. By default, the encoding is - * ISO8859_1 (ISO-Latin-1) but can be changed by calling the constructor which - * takes an encoding. + * A class for turning a character stream into a byte stream. Data written to + * the target input stream is converted into bytes by either a default or a + * provided character converter. The default encoding is taken from the + * "file.encoding" system property. {@code OutputStreamWriter} contains a buffer + * of bytes to be written to target stream and converts these into characters as + * needed. The buffer size is 8K. * * @see InputStreamReader */ - public class OutputStreamWriter extends Writer { private OutputStream out; @@ -48,12 +48,12 @@ private ByteBuffer bytes = ByteBuffer.allocate(8192); /** - * Constructs a new OutputStreamWriter using out as the - * OutputStream to write converted characters to. The default character - * encoding is used (see class description). + * Constructs a new OutputStreamWriter using {@code out} as the target + * stream to write converted characters to. The default character encoding + * is used. * * @param out - * the non-null OutputStream to write converted bytes to. + * the non-null target stream to write converted bytes to. */ public OutputStreamWriter(OutputStream out) { super(out); @@ -67,18 +67,19 @@ } /** - * Constructs a new OutputStreamWriter using out as the - * OutputStream to write converted characters to and enc as - * the character encoding. If the encoding cannot be found, an + * Constructs a new OutputStreamWriter using {@code out} as the target + * stream to write converted characters to and {@code enc} as the character + * encoding. If the encoding cannot be found, an * UnsupportedEncodingException error is thrown. * * @param out - * the non-null OutputStream to write converted bytes to. + * the target stream to write converted bytes to. * @param enc - * the non-null String describing the desired character encoding. - * + * the string describing the desired character encoding. + * @throws NullPointerException + * if {@code enc} is {@code null}. * @throws UnsupportedEncodingException - * if the encoding cannot be found. + * if the encoding specified by {@code enc} cannot be found. */ public OutputStreamWriter(OutputStream out, final String enc) throws UnsupportedEncodingException { @@ -97,15 +98,14 @@ } /** - * Constructs a new OutputStreamWriter using out as the - * OutputStream to write converted characters to and cs as - * the character encoding. - * + * Constructs a new OutputStreamWriter using {@code out} as the target + * stream to write converted characters to and {@code cs} as the character + * encoding. * * @param out - * the non-null OutputStream to write converted bytes to. + * the target stream to write converted bytes to. * @param cs - * the non-null Charset which specify the character encoding. + * the {@code Charset} that specifies the character encoding. */ public OutputStreamWriter(OutputStream out, Charset cs) { super(out); @@ -116,14 +116,14 @@ } /** - * Constructs a new OutputStreamWriter using out as the - * OutputStream to write converted characters to and enc as - * the character encoding. + * Constructs a new OutputStreamWriter using {@code out} as the target + * stream to write converted characters to and {@code enc} as the character + * encoder. * * @param out - * the non-null OutputStream to write converted bytes to. + * the target stream to write converted bytes to. * @param enc - * the non-null CharsetEncoder which used to character encoding. + * the character encoder used for character conversion. */ public OutputStreamWriter(OutputStream out, CharsetEncoder enc) { super(out); @@ -133,16 +133,15 @@ } /** - * Close this OutputStreamWriter. This implementation first flushes the - * buffer and the target OutputStream. The OutputStream is then closed and - * the resources for the buffer and converter are freed. + * Closes this writer. This implementation flushes the buffer as well as the + * target stream. The target stream is then closed and the resources for the + * buffer and converter are released. *

* Only the first invocation of this method has any effect. Subsequent calls - * do no work. + * do nothing. * * @throws IOException - * If an error occurs attempting to close this - * OutputStreamWriter. + * if an error occurs while closing this writer. */ @Override public void close() throws IOException { @@ -159,13 +158,12 @@ } /** - * Flush this OutputStreamWriter. This implementation ensures all buffered - * bytes are written to the target OutputStream. After writing the bytes, - * the target OutputStream is then flushed. + * Flushes this writer. This implementation ensures that all buffered bytes + * are written to the target stream. After writing the bytes, the target + * stream is flushed as well. * * @throws IOException - * If an error occurs attempting to flush this - * OutputStreamWriter. + * if an error occurs while flushing this writer. */ @Override public void flush() throws IOException { @@ -189,14 +187,12 @@ } /** - * Answer the String which identifies the encoding used to convert - * characters to bytes. The value null is returned if this - * Writer has been closed. + * Gets the name of the encoding that is used to convert characters to + * bytes. * - * @return the String describing the converter or null if this Writer is - * closed. + * @return the string describing the converter or {@code null} if this + * writer is closed. */ - public String getEncoding() { if (encoder == null) { return null; @@ -205,24 +201,24 @@ } /** - * Writes count characters starting at offset - * in buf to this Writer. The characters are immediately - * converted to bytes by the character converter and stored in a local - * buffer. If the buffer becomes full as a result of this write, this Writer - * is flushed. + * Writes {@code count} characters starting at {@code offset} in {@code buf} + * to this writer. The characters are immediately converted to bytes by the + * character converter and stored in a local buffer. If the buffer gets full + * as a result of the conversion, this writer is flushed. * * @param buf - * the non-null array containing characters to write. + * the array containing characters to write. * @param offset - * offset in buf to retrieve characters + * the index of the first character in {@code buf} to write. * @param count - * maximum number of characters to write - * - * @throws IOException - * If this OutputStreamWriter has already been closed or some - * other IOException occurs. + * the maximum number of characters to write. * @throws IndexOutOfBoundsException - * If offset or count is outside of bounds. + * if {@code offset < 0} or {@code count < 0}, or if + * {@code offset + count} is greater than the size of + * {@code buf}. + * @throws IOException + * if this writer has already been closed or another I/O error + * occurs. */ @Override public void write(char[] buf, int offset, int count) throws IOException { @@ -252,17 +248,15 @@ } /** - * Writes out the character oneChar to this Writer. The - * low-order 2 bytes are immediately converted to bytes by the character - * converter and stored in a local buffer. If the buffer becomes full as a - * result of this write, this Writer is flushed. + * Writes the character {@code oneChar} to this writer. The lowest two bytes + * of the integer {@code oneChar} are immediately converted to bytes by the + * character converter and stored in a local buffer. If the buffer gets full + * by converting this character, this writer is flushed. * * @param oneChar - * the character to write - * + * the character to write. * @throws IOException - * If this OutputStreamWriter 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 { @@ -274,26 +268,24 @@ } /** - * Writes count characters starting at offset - * in str to this Writer. The characters are immediately - * converted to bytes by the character converter and stored in a local - * buffer. If the buffer becomes full as a result of this write, this Writer - * is flushed. + * Writes {@code count} characters starting at {@code offset} in {@code str} + * to this writer. The characters are immediately converted to bytes by the + * character converter and stored in a local buffer. If the buffer gets full + * as a result of the conversion, this writer is flushed. * * @param str - * the non-null String containing characters to write. + * the 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 - * + * the maximum number of characters to write. * @throws IOException - * If this OutputStreamWriter has already been closed or some - * other IOException occurs. + * if this writer has already been closed or another I/O error + * occurs. * @throws IndexOutOfBoundsException - * If count is negative - * @throws StringIndexOutOfBoundsException - * If offset is negative or offset + count is outside of bounds + * if {@code offset < 0} or {@code count < 0}, or if + * {@code offset + count} is bigger 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/PipedInputStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java Fri May 1 08:08:59 2009 @@ -20,9 +20,9 @@ import org.apache.harmony.luni.util.Msg; /** - * PipedInputStream is a class which receives information on a communications - * pipe. When two threads want to pass data back and forth, one creates a piped - * output stream and the other creates a piped input stream. + * Receives information from a communications pipe. When two threads want to + * pass data back and forth, one creates a piped output stream and the other one + * creates a piped input stream. * * @see PipedOutputStream */ @@ -38,58 +38,56 @@ protected byte buffer[]; /** - * The index in buffer where the next byte will be written. + * The index in {@code buffer} where the next byte will be written. */ protected int in = -1; /** - * The index in buffer where the next byte will be read. + * The index in {@code buffer} where the next byte will be read. */ protected int out = 0; /** - * The size of the default pipe in bytes + * The size of the default pipe in bytes. */ protected static final int PIPE_SIZE = 1024; /** - * Indicates if this pipe is connected + * Indicates if this pipe is connected. */ boolean isConnected = false; /** - * Constructs a new unconnected PipedInputStream. The resulting Stream must - * be connected to a PipedOutputStream before data may be read from it. - * + * Constructs a new unconnected {@code PipedInputStream}. The resulting + * stream must be connected to a {@link PipedOutputStream} before data may + * be read from it. */ public PipedInputStream() { /* empty */ } /** - * Constructs a new PipedInputStream connected to the PipedOutputStream - * out. Any data written to the output stream can be read - * from the this input stream. + * Constructs a new {@code PipedInputStream} connected to the + * {@link PipedOutputStream} {@code out}. Any data written to the output + * stream can be read from the this input stream. * * @param out - * the PipedOutputStream to connect to. - * + * the piped output stream to connect to. * @throws IOException - * if this or out are already connected. + * if this stream or {@code out} are already connected. */ public PipedInputStream(PipedOutputStream out) throws IOException { connect(out); } /** - * Answers a int representing the number of bytes that are available before - * this PipedInputStream will block. This method returns the number of bytes - * written to the pipe but not read yet up to the size of the pipe. - * - * @return int the number of bytes available before blocking. + * Returns the number of bytes that are available before this stream will + * block. This implementation returns the number of bytes written to this + * pipe that have not been read yet. * + * @return the number of bytes available before blocking. * @throws IOException - * If an error occurs in this stream. + * if an error occurs in this stream. */ @Override public synchronized int available() throws IOException { @@ -100,11 +98,11 @@ } /** - * Close this PipedInputStream. This implementation releases the buffer used - * for the pipe and notifies all threads waiting to read or write. + * Closes this stream. This implementation releases the buffer used for the + * pipe and notifies all threads waiting to read or write. * * @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 { @@ -118,33 +116,36 @@ } /** - * Connects this PipedInputStream to a PipedOutputStream. Any data written - * to the OutputStream becomes readable in this InputStream. + * Connects this {@code PipedInputStream} to a {@link PipedOutputStream}. + * Any data written to the output stream becomes readable in this input + * stream. * * @param src - * the source PipedOutputStream. - * + * the source output stream. * @throws IOException - * If either stream is already connected. + * if either stream is already connected. */ public void connect(PipedOutputStream src) throws IOException { src.connect(this); } /** - * Reads a single byte from this PipedInputStream and returns the result as - * an int. The low-order byte is returned or -1 of the end of stream was - * encountered. If there is no data in the pipe, this method blocks until - * there is data available. Separate threads should be used for the reader - * of the PipedInputStream and the PipedOutputStream. There may be - * undesirable results if more than one Thread interacts a input or output - * pipe. - * - * @return int 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 this stream has been + * reached. If there is no data in the pipe, this method blocks until data + * is available, the end of the stream is detected or an exception is + * thrown. + *

+ * Separate threads should be used to read from a {@code PipedInputStream} + * and to write to the connected {@link PipedOutputStream}. If the same + * thread is used, a deadlock may occur. + * + * @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 not connected to an output + * stream, or if the thread writing to the connected output + * stream is no longer alive. */ @Override public synchronized int read() throws IOException { @@ -191,25 +192,35 @@ } /** - * Reads at most count bytes from this PipedInputStream and - * stores them in byte array buffer starting at - * offset. Answer the number of bytes actually read or -1 if - * no bytes were read and end of stream was encountered. Separate threads - * should be used for the reader of the PipedInputStream and the - * PipedOutputStream. There may be undesirable results if more than one - * Thread interacts a input or output pipe. - * + * Reads at most {@code count} bytes from this stream and stores them in the + * byte array {@code bytes} starting at {@code offset}. Blocks until at + * least one byte has been read, the end of the stream is detected or an + * exception is thrown. + *

+ * Separate threads should be used to read from a {@code PipedInputStream} + * and to write to the connected {@link PipedOutputStream}. If the same + * thread is used, a deadlock may occur. + * * @param bytes - * the byte array in which to store the read bytes. + * the array in which to store the bytes read. * @param offset - * the offset in buffer to store the read bytes. + * the initial position in {@code bytes} to store the bytes + * read from this stream. * @param count - * the maximum number of bytes to store in buffer. - * @return the number of bytes actually read or -1 if end of stream. - * + * the maximum number of bytes to store in {@code bytes}. + * @return the number of bytes actually read or -1 if the end of the stream + * has been reached. + * @throws IndexOutOfBoundsException + * if {@code offset < 0} or {@code count < 0}, or if {@code + * offset + count} is greater than the size of {@code bytes}. + * @throws InterruptedIOException + * if the thread reading from this stream is interrupted. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or not connected to an output + * stream, or if the thread writing to the connected output + * stream is no longer alive. + * @throws NullPointerException + * if {@code bytes} is {@code null}. */ @Override public synchronized int read(byte[] bytes, int offset, int count) @@ -299,19 +310,21 @@ } /** - * Receives a byte and stores it into the PipedInputStream. This called by - * PipedOutputStream.write() when writes occur. The lowest-order byte is - * stored at index in in the buffer. - *

- * If the buffer is full and the thread sending #receive is interrupted, the - * InterruptedIOException will be thrown. + * Receives a byte and stores it in this stream's {@code buffer}. This + * method is called by {@link PipedOutputStream#write(int)}. The least + * significant byte of the integer {@code oneByte} is stored at index + * {@code in} in the {@code buffer}. + *

+ * This method blocks as long as {@code buffer} is full. * * @param oneByte - * the byte to store into the pipe. - * + * the byte to store in this pipe. + * @throws InterruptedIOException + * if the {@code buffer} is full and the thread that has called + * this method is interrupted. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or the thread that has last read + * from this stream is no longer alive. */ protected synchronized void receive(int oneByte) throws IOException { if (buffer == null || isClosed) { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java Fri May 1 08:08:59 2009 @@ -20,9 +20,9 @@ import org.apache.harmony.luni.util.Msg; /** - * PipedOutputStream is a class which places information on a communications - * pipe. When two threads want to pass data back and forth, one creates a piped - * output stream and the other creates a piped input stream. + * Places information on a communications pipe. When two threads want to pass + * data back and forth, one creates a piped output stream and the other one + * creates a piped input stream. * * @see PipedInputStream */ @@ -34,23 +34,23 @@ private PipedInputStream dest; /** - * Constructs a new unconnected PipedOutputStream. The resulting Stream must - * be connected to a PipedInputStream before data may be written to it. + * Constructs a new unconnected {@code PipedOutputStream}. The resulting + * stream must be connected to a {@link PipedInputStream} before data can be + * written to it. */ public PipedOutputStream() { super(); } /** - * Constructs a new PipedOutputStream connected to the PipedInputStream - * dest. Any data written to this stream can be read from - * the dest. + * Constructs a new {@code PipedOutputStream} connected to the + * {@link PipedInputStream} {@code dest}. Any data written to this stream + * can be read from the target stream. * * @param dest - * the PipedInputStream to connect to. - * + * the piped input stream to connect to. * @throws IOException - * if dest is already connected. + * if this stream or {@code dest} are already connected. */ public PipedOutputStream(PipedInputStream dest) throws IOException { super(); @@ -58,13 +58,11 @@ } /** - * Close this PipedOutputStream. Any data buffered in the corresponding - * PipedInputStream can be read, then -1 will be returned to the reader. If - * this OutputStream is not connected, this method does nothing. + * Closes this stream. If this stream is connected to an input stream, the + * input stream is closed and the pipe is disconnected. * * @throws IOException - * If an error occurs attempting to close this - * PipedOutputStream. + * if an error occurs while closing this stream. */ @Override public void close() throws IOException { @@ -76,14 +74,13 @@ } /** - * Connects this PipedOutputStream to a PipedInputStream. Any data written - * to this OutputStream becomes readable in the InputStream. + * Connects this stream to a {@link PipedInputStream}. Any data written to + * this output stream becomes readable in the input stream. * * @param stream - * the destination PipedInputStream. - * + * the destination input stream. * @throws IOException - * If this Stream or the dest is already connected. + * if either stream is already connected. */ public void connect(PipedInputStream stream) throws IOException { if (null == stream) { @@ -103,11 +100,11 @@ } /** - * Notifies the readers on the PipedInputStream that bytes can be read. This - * method does nothing if this Stream is not connected. + * Notifies the readers of this {@link PipedInputStream} that bytes can be + * read. This method does nothing if this stream is not connected. * * @throws IOException - * If an IO error occurs during the flush. + * if an I/O error occurs while flushing this stream. */ @Override public void flush() throws IOException { @@ -119,31 +116,32 @@ } /** - * Writes count bytes from this byte array - * buffer starting at offset index to this - * PipedOutputStream. The written data can now be read from the destination - * PipedInputStream. Separate threads should be used for the reader of the - * PipedInputStream and the PipedOutputStream. There may be undesirable - * results if more than one Thread interacts a input or output pipe. - * + * Writes {@code count} bytes from the byte array {@code buffer} starting at + * {@code offset} to this stream. The written data can then be read from the + * connected input stream. + *

+ * Separate threads should be used to write to a {@code PipedOutputStream} + * and to read from the connected {@link PipedInputStream}. If the same + * thread is used, a deadlock may occur. + * * @param buffer - * the buffer to be written + * the buffer to write. * @param offset - * offset in buffer to get bytes + * the index of the first byte in {@code buffer} to write. * @param count - * number of bytes in buffer to write - * - * @throws IOException - * If the receiving thread was terminated without closing the - * pipe. This case is not currently handled correctly. + * the number of bytes from {@code buffer} to write to this + * stream. + * @throws IndexOutOfBoundsException + * if {@code offset < 0} or {@code count < 0}, or if {@code + * offset + count} is bigger than the length of {@code buffer}. * @throws InterruptedIOException - * If the pipe is full and the current thread is interrupted + * if the pipe is full and the current thread is interrupted * waiting for space to write data. This case is not currently * handled correctly. - * @throws NullPointerException - * If the receiver has not been connected yet. - * @throws IllegalArgumentException - * If any of the arguments are out of bounds. + * @throws IOException + * if this stream is not connected, if the target stream is + * closed or if the thread reading from the target stream is no + * longer alive. This case is currently not handled correctly. */ @Override public void write(byte buffer[], int offset, int count) throws IOException { @@ -155,25 +153,24 @@ } /** - * Writes the specified byte oneByte to this - * PipedOutputStream. Only the low order byte of oneByte is - * written. The data can now be read from the destination PipedInputStream. - * Separate threads should be used for the reader of the PipedInputStream - * and the PipedOutputStream. There may be undesirable results if more than - * one Thread interacts a input or output pipe. + * Writes a single byte to this stream. Only the least significant byte of + * the integer {@code oneByte} is written. The written byte can then be read + * from the connected input stream. + *

+ * Separate threads should be used to write to a {@code PipedOutputStream} + * and to read from the connected {@link PipedInputStream}. If the same + * thread is used, a deadlock may occur. * * @param oneByte - * the byte to be written - * - * @throws IOException - * If the receiving thread was terminated without closing the - * pipe. This case is not currently handled correctly. + * the byte to write. * @throws InterruptedIOException - * If the pipe is full and the current thread is interrupted + * if the pipe is full and the current thread is interrupted * waiting for space to write data. This case is not currently * handled correctly. - * @throws NullPointerException - * If the receiver has not been connected yet. + * @throws IOException + * if this stream is not connected, if the target stream is + * closed or if the thread reading from the target stream is no + * longer alive. This case is currently not handled correctly. */ @Override public void write(int oneByte) throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java Fri May 1 08:08:59 2009 @@ -20,9 +20,11 @@ import org.apache.harmony.luni.util.Msg; /** - * PipedReader is a class which receives information on a communications pipe. - * When two threads want to pass data back and forth, one creates a piped writer - * and the other creates a piped reader. + * Receives information on a communications pipe. When two threads want to pass + * data back and forth, one creates a piped writer and the other creates a piped + * reader. + * + * @see PipedWriter */ public class PipedReader extends Reader { @@ -38,13 +40,13 @@ private char data[]; /** - * The index in buffer where the next character will be + * The index in {@code buffer} where the next character will be * written. */ private int in = -1; /** - * The index in buffer where the next character will be read. + * The index in {@code buffer} where the next character will be read. */ private int out; @@ -59,23 +61,25 @@ private boolean isConnected; /** - * Constructs a new unconnected PipedReader. The resulting Reader must be - * connected to a PipedWriter before data may be read from it. + * Constructs a new unconnected {@code PipedReader}. The resulting reader + * must be connected to a {@code PipedWriter} before data may be read from + * it. + * + * @see PipedWriter */ public PipedReader() { data = new char[PIPE_SIZE]; } /** - * Constructs a new PipedReader connected to the PipedWriter - * out. Any data written to the writer can be read from the - * this reader. + * Constructs a new {@code PipedReader} connected to the {@link PipedWriter} + * {@code out}. Any data written to the writer can be read from the this + * reader. * * @param out - * the PipedWriter to connect to. - * + * the {@code PipedWriter} to connect to. * @throws IOException - * if this or out are already connected. + * if {@code out} is already connected. */ public PipedReader(PipedWriter out) throws IOException { this(); @@ -83,11 +87,11 @@ } /** - * Close this PipedReader. This implementation releases the buffer used for + * Closes this reader. This implementation releases the buffer used for * the pipe and notifies all threads waiting to read or write. * * @throws IOException - * If an error occurs attempting to close this reader. + * if an error occurs while closing this reader. */ @Override public void close() throws IOException { @@ -101,14 +105,14 @@ } /** - * Connects this PipedReader to a PipedWriter. Any data written to the - * Writer becomes available in this Reader. + * Connects this {@code PipedReader} to a {@link PipedWriter}. Any data + * written to the writer becomes readable in this reader. * * @param src - * the source PipedWriter. - * + * the writer to connect to. * @throws IOException - * If either Writer or Reader is already connected. + * if this reader is closed or already connected, or if {@code + * src} is already connected. */ public void connect(PipedWriter src) throws IOException { synchronized (lock) { @@ -117,7 +121,7 @@ } /** - * Establish the connection to the PipedWriter. + * Establishes the connection to the PipedWriter. * * @throws IOException * If this Reader is already connected. @@ -135,17 +139,20 @@ } /** - * Reads the next character from this Reader. Answer the character actually - * read or -1 if no character was read and end of reader was encountered. - * Separate threads should be used for the reader of the PipedReader and the - * PipedWriter. There may be undesirable results if more than one Thread - * interacts a reader or writer pipe. - * - * @return int the character read -1 if end of reader. - * + * Reads a single character from this reader and returns it as an integer + * with the two higher-order bytes set to 0. Returns -1 if the end of the + * reader has been reached. If there is no data in the pipe, this method + * blocks until data is available, the end of the reader is detected or an + * exception is thrown. + *

+ * Separate threads should be used to read from a {@code PipedReader} and to + * write to the connected {@link PipedWriter}. If the same thread is used, + * a deadlock may occur. + * + * @return the character read or -1 if the end of the reader has been + * reached. * @throws IOException - * If the reader is already closed or another IOException - * occurs. + * if this reader is closed or some other I/O error occurs. */ @Override public int read() throws IOException { @@ -155,28 +162,34 @@ } /** - * Reads at most count character from this PipedReader and - * stores them in char array buffer starting at - * offset. Answer the number of characters actually read or - * -1 if no characters were read and end of stream was encountered. Separate - * threads should be used for the reader of the PipedReader and the - * PipedWriter. There may be undesirable results if more than one Thread - * interacts a reader or writer pipe. + * Reads at most {@code count} characters from this reader and stores them + * in the character array {@code buffer} starting at {@code offset}. If + * there is no data in the pipe, this method blocks until at least one byte + * has been read, the end of the reader is detected or an exception is + * thrown. + *

+ * Separate threads should be used to read from a {@code PipedReader} and to + * write to the connected {@link PipedWriter}. If the same thread is used, a + * deadlock may occur. * * @param buffer - * the character array in which to store the read characters. + * the character array in which to store the characters read. * @param offset - * the offset in buffer to store the read - * characters. + * the initial position in {@code bytes} to store the characters + * read from this reader. * @param count - * the maximum number of characters to store in - * buffer. - * @return int the number of characters actually read or -1 if end of - * reader. - * + * the maximum number of characters to store in {@code buffer}. + * @return the number of characters read or -1 if the end of the reader has + * been reached. + * @throws IndexOutOfBoundsException + * if {@code offset < 0} or {@code count < 0}, or if {@code + * offset + count} is greater than the size of {@code buffer}. + * @throws InterruptedIOException + * if the thread reading from this reader is interrupted. * @throws IOException - * If the reader is already closed or another IOException - * occurs. + * if this reader is closed or not connected to a writer, or if + * the thread writing to the connected writer is no longer + * alive. */ @Override public int read(char[] buffer, int offset, int count) throws IOException { @@ -261,15 +274,18 @@ } /** - * Answer a boolean indicating whether or not this Reader is ready to be - * read. Answers true if the buffer contains characters to be read. - * - * @return boolean true if there are characters ready, - * false otherwise. + * Indicates whether this reader is ready to be read without blocking. + * Returns {@code true} if this reader will not block when {@code read} is + * called, {@code false} if unknown or blocking will occur. This + * implementation returns {@code true} if the internal buffer contains + * characters that can be read. * + * @return always {@code false}. * @throws IOException - * If the reader is already closed or another IOException - * occurs. + * if this reader is closed or not connected, or if some other + * I/O error occurs. + * @see #read() + * @see #read(char[], int, int) */ @Override public boolean ready() throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java Fri May 1 08:08:59 2009 @@ -20,9 +20,9 @@ import org.apache.harmony.luni.util.Msg; /** - * PipedWriter is a class which places information on a communications pipe. - * When two threads want to pass data back and forth, one creates a piped writer - * and the other creates a piped reader. + * Places information on a communications pipe. When two threads want to pass + * data back and forth, one creates a piped writer and the other creates a piped + * reader. * * @see PipedReader */ @@ -35,23 +35,25 @@ private boolean closed; /** - * Constructs a new unconnected PipedWriter. The resulting Stream must be - * connected to a PipedReader before data may be written to it. + * Constructs a new unconnected {@code PipedWriter}. The resulting writer + * must be connected to a {@code PipedReader} before data may be written to + * it. + * + * @see PipedReader */ public PipedWriter() { super(); } /** - * Constructs a new PipedWriter connected to the PipedReader - * dest. Any data written to this Writer can be read from - * the dest. + * Constructs a new {@code PipedWriter} connected to the {@link PipedReader} + * {@code dest}. Any data written to this writer can be read from {@code + * dest}. * * @param dest - * the PipedReader to connect to. - * - * @throws java.io.IOException - * if dest is already connected. + * the {@code PipedReader} to connect to. + * @throws IOException + * if {@code dest} is already connected. */ public PipedWriter(PipedReader dest) throws IOException { super(dest); @@ -59,12 +61,12 @@ } /** - * Close this PipedWriter. Any data buffered in the corresponding - * PipedReader can be read, then -1 will be returned to the reader. If this - * Writer is not connected, this method does nothing. + * Closes this writer. If a {@link PipedReader} is connected to this writer, + * it is closed as well and the pipe is disconnected. Any data buffered in + * the reader can still be read. * - * @throws java.io.IOException - * If an error occurs attempting to close this PipedWriter. + * @throws IOException + * if an error occurs while closing this writer. */ @Override public void close() throws IOException { @@ -79,14 +81,14 @@ } /** - * Connects this PipedWriter to a PipedReader. Any data written to this - * Writer becomes readable in the Reader. + * Connects this {@code PipedWriter} to a {@link PipedReader}. Any data + * written to this writer becomes readable in the reader. * * @param stream - * the destination PipedReader. - * - * @throws java.io.IOException - * If this Writer or the dest is already connected. + * the reader to connect to. + * @throws IOException + * if this writer is closed or already connected, or if {@code + * stream} is already connected. */ public void connect(PipedReader stream) throws IOException { synchronized (lock) { @@ -102,11 +104,11 @@ } /** - * Notifies the readers on the PipedReader that characters can be read. This + * Notifies the readers of this {@code PipedReader} that characters can be read. This * method does nothing if this Writer is not connected. * - * @throws java.io.IOException - * If an IO error occurs during the flush. + * @throws IOException + * if an I/O error occurs while flushing this writer. */ @Override public void flush() throws IOException { @@ -116,31 +118,35 @@ } /** - * Writes count chars from the char array - * buffer starting at offset index to this - * PipedWriter. The written data can now be read from the destination - * PipedReader. Separate threads should be used for the reader of the - * PipedReader and the PipedWriter. There may be undesirable results if more - * than one Thread interacts a input or output pipe. - * + * Writes {@code count} characters from the character array {@code buffer} + * starting at offset {@code index} to this writer. The written data can + * then be read from the connected {@link PipedReader} instance. + *

+ * Separate threads should be used to write to a {@code PipedWriter} and to + * read from the connected {@code PipedReader}. If the same thread is used, + * a deadlock may occur. + * * @param buffer - * the buffer to be written + * the buffer to write. * @param offset - * offset in buffer to get chars + * the index of the first character in {@code buffer} to write. * @param count - * number of chars in buffer to write - * - * @throws java.io.IOException - * If the receiving thread was terminated without closing the - * pipe. This case is not currently handled correctly. - * @throws java.io.InterruptedIOException - * If the pipe is full and the current thread is interrupted + * the number of characters from {@code buffer} to write to this + * writer. + * @throws IndexOutOfBoundsException + * if {@code offset < 0} or {@code count < 0}, or if {@code + * offset + count} is bigger than the length of {@code buffer}. + * @throws InterruptedIOException + * if the pipe is full and the current thread is interrupted * waiting for space to write data. This case is not currently * handled correctly. - * @throws java.lang.NullPointerException - * If the receiver has not been connected yet. - * @throws java.lang.IllegalArgumentException - * If any of the arguments are out of bounds. + * @throws IOException + * if this writer is closed or not connected, if the target + * reader is closed or if the thread reading from the target + * reader is no longer alive. This case is currently not handled + * correctly. + * @throws NullPointerException + * if {@code buffer} is {@code null}. */ @Override public void write(char buffer[], int offset, int count) throws IOException { @@ -165,24 +171,24 @@ } /** - * Writes the character c to this PipedWriter. The written - * data can now be read from the destination PipedReader. Separate threads - * should be used for the reader of the PipedReader and the PipedWriter. - * There may be undesirable results if more than one Thread interacts a - * input or output pipe. + * Writes a single character {@code c} to this writer. This character can + * then be read from the connected {@link PipedReader} instance. + *

+ * Separate threads should be used to write to a {@code PipedWriter} and to + * read from the connected {@code PipedReader}. If the same thread is used, + * a deadlock may occur. * * @param c - * the character to be written - * - * @throws java.io.IOException - * If the receiving thread was terminated without closing the - * pipe. This case is not currently handled correctly. - * @throws java.io.InterruptedIOException - * If the pipe is full and the current thread is interrupted + * the character to write. + * @throws InterruptedIOException + * if the pipe is full and the current thread is interrupted * waiting for space to write data. This case is not currently * handled correctly. - * @throws java.lang.NullPointerException - * If the receiver has not been connected yet. + * @throws IOException + * if this writer is closed or not connected, if the target + * reader is closed or if the thread reading from the target + * reader is no longer alive. This case is currently not handled + * correctly. */ @Override public void write(int c) throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java Fri May 1 08:08:59 2009 @@ -28,13 +28,12 @@ import org.apache.harmony.luni.util.PriviAction; /** - * PrintStream is a class which takes an OutputStream and provides convenience - * methods for printing common data types in a human readable format on the - * stream. This is not to be confused with DataOutputStream which is used for - * encoding common data types so that they can be read back in. No IOExceptions - * are thrown by this class. Instead, callers should call checkError() to see if - * a problem has been encountered in this Stream. - * + * Wraps an existing {@link OutputStream} and provides convenience methods for + * writing common data types in a human readable format. This is not to be + * confused with DataOutputStream which is used for encoding common data types + * so that they can be read back in. No {@code IOException} is thrown by this + * class. Instead, callers should use {@link #checkError()} to see if a problem + * has occurred in this stream. */ public class PrintStream extends FilterOutputStream implements Appendable, Closeable { @@ -60,13 +59,14 @@ // private Formatter formatter; /** - * Constructs a new PrintStream on the OutputStream out. All - * writes to the target can now take place through this PrintStream. By - * default, the PrintStream is set to not autoflush when a newline is - * encountered. + * Constructs a new {@code PrintStream} with {@code out} as its target + * stream. By default, the new print stream does not automatically flush its + * contents to the target stream when a newline is encountered. * * @param out - * the OutputStream to provide convenience methods on. + * the target output stream. + * @throws NullPointerException + * if {@code out} is {@code null}. */ public PrintStream(OutputStream out) { super(out); @@ -76,16 +76,18 @@ } /** - * Constructs a new PrintStream on the OutputStream out. All - * writes to the target can now take place through this PrintStream. The - * PrintStream is set to not autoflush if autoflush is - * true. + * Constructs a new {@code PrintStream} with {@code out} as its target + * stream. The parameter {@code autoflush} determines if the print stream + * automatically flushes its contents to the target stream when a newline is + * encountered. * * @param out - * the OutputStream to provide convenience methods on. + * the target output stream. * @param autoflush - * indicates whether or not to flush contents upon encountering a + * indicates whether to flush contents upon encountering a * newline sequence. + * @throws NullPointerException + * if {@code out} is {@code null}. */ public PrintStream(OutputStream out, boolean autoflush) { super(out); @@ -96,21 +98,22 @@ } /** - * Constructs a new PrintStream on the OutputStream out. All - * writes to the target can now take place through this PrintStream. The - * PrintStream is set to not autoflush if autoflush is - * true. + * Constructs a new {@code PrintStream} with {@code out} as its target + * stream and using the character encoding {@code enc} while writing. The + * parameter {@code autoflush} determines if the print stream automatically + * flushes its contents to the target stream when a newline is encountered. * * @param out - * the OutputStream to provide convenience methods on. + * the target output stream. * @param autoflush * indicates whether or not to flush contents upon encountering a * newline sequence. * @param enc - * the non-null String describing the desired character encoding. - * + * the non-null string describing the desired character encoding. + * @throws NullPointerException + * if {@code out} or {@code enc} are {@code null}. * @throws UnsupportedEncodingException - * If the chosen encoding is not supported + * if the encoding specified by {@code enc} is not supported. */ public PrintStream(OutputStream out, boolean autoflush, String enc) throws UnsupportedEncodingException { @@ -130,42 +133,40 @@ } /** - * Constructs a new PrintStream on the file file. All writes - * to the target can now take place through this PrintStream. Its encoding - * character set is the default charset in the VM. + * Constructs a new {@code PrintStream} with {@code file} as its target. The + * virtual machine's default character set is used for character encoding. * * @param file - * the file to provide convenience methods on. + * the target file. If the file already exists, its contents are + * removed, otherwise a new file is created. * @throws FileNotFoundException - * if the file does not exist or cannot be opened to write. Or - * the file cannot be created or any problem when open the file - * to write. + * if an error occurs while opening or creating the target file. * @throws SecurityException - * if the security manager exists and denies the write to the - * file. + * if a security manager exists and it denies writing to the + * target file. */ public PrintStream(File file) throws FileNotFoundException { super(new FileOutputStream(file)); } /** - * Constructs a new PrintStream on the file file. All writes - * to the target can now take place through this PrintStream. Its encoding - * character set name is csn. + * Constructs a new {@code PrintStream} with {@code file} as its target. The + * character set named {@code csn} is used for character encoding. * * @param file - * the file to provide convenience methods on. + * the target file. If the file already exists, its contents are + * removed, otherwise a new file is created. * @param csn - * the character set name + * the name of the character set used for character encoding. * @throws FileNotFoundException - * if the file does not exist or cannot be opened to write. Or - * the file cannot be created or any problem when open the file - * to write. + * if an error occurs while opening or creating the target file. + * @throws NullPointerException + * if {@code csn} is {@code null}. * @throws SecurityException - * if the security manager exists and denies the write to the - * file. + * if a security manager exists and it denies writing to the + * target file. * @throws UnsupportedEncodingException - * if the chosen character set is not supported + * if the encoding specified by {@code csn} is not supported. */ public PrintStream(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException { @@ -180,42 +181,42 @@ } /** - * Constructs a new PrintStream on the file the name of which isfileName. - * All writes to the target can now take place through this PrintStream. Its - * encoding character set is the default charset in the VM. + * Constructs a new {@code PrintStream} with the file identified by + * {@code fileName} as its target. The virtual machine's default character + * set is used for character encoding. * * @param fileName - * the file to provide convenience methods on. + * the target file's name. If the file already exists, its + * contents are removed, otherwise a new file is created. * @throws FileNotFoundException - * if the file does not exist or cannot be opened to write. Or - * the file cannot be created or any problem when open the file - * to write. + * if an error occurs while opening or creating the target file. * @throws SecurityException - * if the security manager exists and denies the write to the - * file. + * if a security manager exists and it denies writing to the + * target file. */ public PrintStream(String fileName) throws FileNotFoundException { this(new File(fileName)); } /** - * Constructs a new PrintStream on the file the name of which isfileName. - * All writes to the target can now take place through this PrintStream. Its - * encoding character set name is csn. + * Constructs a new {@code PrintStream} with the file identified by + * {@code fileName} as its target. The character set named {@code csn} is + * used for character encoding. * * @param fileName - * the file to provide convenience methods on. + * the target file's name. If the file already exists, its + * contents are removed, otherwise a new file is created. * @param csn - * the character set name + * the name of the character set used for character encoding. * @throws FileNotFoundException - * if the file does not exist or cannot be opened to write. Or - * the file cannot be created or any problem when open the file - * to write. + * if an error occurs while opening or creating the target file. + * @throws NullPointerException + * if {@code csn} is {@code null}. * @throws SecurityException - * if the security manager exists and denies the write to the - * file. + * if a security manager exists and it denies writing to the + * target file. * @throws UnsupportedEncodingException - * if the chosen character set is not supported + * if the encoding specified by {@code csn} is not supported. */ public PrintStream(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException { @@ -223,13 +224,12 @@ } /** - * Answers a boolean indicating whether or not this PrintStream has - * encountered an error. If so, the receiver should probably be closed since - * further writes will not actually take place. A side effect of calling - * checkError is that the target OutputStream is flushed. + * Flushes this stream and returns the value of the error flag. * - * @return true if an error occurred in this PrintStream, - * false otherwise. + * @return {@code true} if either an {@code IOException} has been thrown + * previously or if {@code setError()} has been called; + * {@code false} otherwise. + * @see #setError() */ public boolean checkError() { if (out != null) { @@ -239,9 +239,9 @@ } /** - * Close this PrintStream. This implementation flushes and then closes the - * target stream. If an error occurs, set an error in this PrintStream to - * true. + * Closes this print stream. Flushes this stream and then closes the target + * stream. If an I/O error occurs, this stream's error state is set to + * {@code true}. */ @Override public synchronized void close() { @@ -257,9 +257,9 @@ } /** - * Flush this PrintStream to ensure all pending data is sent out to the - * target OutputStream. This implementation flushes the target OutputStream. - * If an error occurs, set an error in this PrintStream to true. + * Ensures that all pending data is sent out to the target stream. It also + * flushes the target stream. If an I/O error occurs, this stream's error + * state is set to {@code true}. */ @Override public synchronized void flush() { @@ -275,50 +275,49 @@ } /** - * Writes a string formatted by an intermediate Formatter to - * this stream using the given format string and arguments. - *

- * The method uses the default for the current JVM instance locale, as if it - * is specified by the Locale.getDefault() call. + * Writes a string formatted by an intermediate {@code Formatter} to the + * target stream using the specified format string and arguments. For the + * locale, the default value of the current virtual machine instance is + * used. * * @param format - * A format string. + * the format string used for {@link java.util.Formatter#format}. * @param args - * The arguments list. If there are more arguments than those - * specified by the format string, then the additional arguments - * are ignored. - * @return This stream. + * the list of arguments passed to the formatter. If there are + * more arguments than required by the {@code format} string, + * then the additional arguments are ignored. + * @return this stream. * @throws IllegalFormatException - * If the format string is illegal or incompatible with the - * arguments or the arguments are less than those required by - * the format string or any other illegal situation. + * if the format string is illegal or incompatible with the + * arguments, if there are not enough arguments or if any other + * error regarding the format string or arguments is detected. * @throws NullPointerException - * If the given format is null. + * if {@code format} is {@code null}. */ public PrintStream format(String format, Object... args) { return format(Locale.getDefault(), format, args); } /** - * Writes a string formatted by an intermediate Formatter to - * this stream using the given format string and arguments. + * Writes a string formatted by an intermediate {@link Formatter} to this + * stream using the specified locale, format string and arguments. * * @param l - * The locale used in the method. If locale is null, then no - * localization will be applied. + * the locale used in the method. No localization will be applied + * if {@code l} is {@code null}. * @param format - * A format string. + * the format string used for {@link java.util.Formatter#format}. * @param args - * The arguments list. If there are more arguments than those - * specified by the format string, then the additional arguments - * are ignored. - * @return This stream. + * the list of arguments passed to the formatter. If there are + * more arguments than required by the {@code format} string, + * then the additional arguments are ignored. + * @return this stream. * @throws IllegalFormatException - * If the format string is illegal or incompatible with the - * arguments or the arguments are less than those required by - * the format string or any other illegal situation. + * if the format string is illegal or incompatible with the + * arguments, if there are not enough arguments or if any other + * error regarding the format string or arguments is detected. * @throws NullPointerException - * If the given format is null. + * if {@code format} is {@code null}. */ public PrintStream format(Locale l, String format, Object... args) { if (format == null) { @@ -330,25 +329,23 @@ /** * Prints a formatted string. The behavior of this method is the same as - * this stream's format(String format, Object... args) - * method. - *

- * The method uses the default for the current JVM instance locale, as if it - * is specified by the Locale.getDefault() call. + * this stream's {@code #format(String, Object...)} method. For the locale, + * the default value of the current virtual machine instance is used. * * @param format - * A format string. + * the format string used for + * {@link java.util.Formatter#format}. * @param args - * The arguments list. If there are more arguments than those - * specified by the format string, then the additional arguments - * are ignored. - * @return This stream. + * the list of arguments passed to the formatter. If there are + * more arguments than required by the {@code format} string, + * then the additional arguments are ignored. + * @return this stream. * @throws IllegalFormatException - * If the format string is illegal or incompatible with the - * arguments or the arguments are less than those required by - * the format string or any other illegal situation. + * if the format string is illegal or incompatible with the + * arguments, if there are not enough arguments or if any other + * error regarding the format string or arguments is detected. * @throws NullPointerException - * If the given format is null. + * if {@code format} is {@code null}. */ public PrintStream printf(String format, Object... args) { return format(format, args); @@ -356,25 +353,24 @@ /** * Prints a formatted string. The behavior of this method is the same as - * this writer's - * format(Locale l, String format, Object... args) method. + * this stream's {@code #format(Locale, String, Object...)} method. * * @param l - * The locale used in the method. If locale is null, then no - * localization will be applied. + * the locale used in the method. No localization will be applied + * if {@code l} is {@code null}. * @param format - * A format string. + * the format string used for {@link java.util.Formatter#format}. * @param args - * The arguments list. If there are more arguments than those - * specified by the format string, then the additional arguments - * are ignored. - * @return This stream. + * the list of arguments passed to the formatter. If there are + * more arguments than required by the {@code format} string, + * then the additional arguments are ignored. + * @return this stream. * @throws IllegalFormatException - * If the format string is illegal or incompatible with the - * arguments or the arguments are less than those required by - * the format string or any other illegal situation. + * if the format string is illegal or incompatible with the + * arguments, if there are not enough arguments or if any other + * error regarding the format string or arguments is detected. * @throws NullPointerException - * If the given format is null. + * if {@code format} is {@code null}. */ public PrintStream printf(Locale l, String format, Object... args) { return format(l, format, args); @@ -388,88 +384,100 @@ } /** - * Prints the String representation of the character array parameter - * charArray to the target OutputStream. + * Prints the string representation of the specified character array + * to the target stream. * * @param charArray - * the character array to print on this PrintStream. + * the character array to print to the target stream. + * @see #print(String) */ public void print(char[] charArray) { print(new String(charArray, 0, charArray.length)); } /** - * Prints the String representation of the character parameter - * ch to the target OutputStream. + * Prints the string representation of the specified character to the target + * stream. * * @param ch - * the character to print on this PrintStream. + * the character to print to the target stream. + * @see #print(String) */ public void print(char ch) { print(String.valueOf(ch)); } /** - * Prints the String representation of the double parameter - * dnum to the target OutputStream. + * Prints the string representation of the specified double to the target + * stream. * * @param dnum - * the double to print on this PrintStream. + * the double value to print to the target stream. + * @see #print(String) */ public void print(double dnum) { print(String.valueOf(dnum)); } /** - * Prints the String representation of the float parameter - * fnum to the target OutputStream. + * Prints the string representation of the specified float to the target + * stream. * * @param fnum - * the float to print on this PrintStream. + * the float value to print to the target stream. + * @see #print(String) */ public void print(float fnum) { print(String.valueOf(fnum)); } /** - * Obtains the int argument as a String and - * prints it to the target {@link OutputStream}. + * Prints the string representation of the specified integer to the target + * stream. * * @param inum - * the int to print on this PrintStream. + * the integer value to print to the target stream. + * @see #print(String) */ public void print(int inum) { print(String.valueOf(inum)); } /** - * Prints the String representation of the long parameter - * lnum to the target OutputStream. + * Prints the string representation of the specified long to the target + * stream. * * @param lnum - * the long to print on this PrintStream. + * the long value to print to the target stream. + * @see #print(String) */ public void print(long lnum) { print(String.valueOf(lnum)); } /** - * Prints the String representation of the Object parameter obj - * to the target OutputStream. + * Prints the string representation of the specified object to the target + * stream. * * @param obj - * the Object to print on this PrintStream. + * the object to print to the target stream. + * @see #print(String) */ public void print(Object obj) { print(String.valueOf(obj)); } /** - * Prints the String representation of the String parameter - * str to the target OutputStream. - * + * Prints a string to the target stream. The string is converted to an array + * of bytes using the encoding chosen during the construction of this + * stream. The bytes are then written to the target stream with + * {@code write(int)}. + *

+ * If an I/O error occurs, this stream's error state is set to {@code true}. + * * @param str - * the String to print on this PrintStream. + * the string to print to the target stream. + * @see #write(int) */ public synchronized void print(String str) { if (out == null) { @@ -493,116 +501,121 @@ } /** - * Prints the String representation of the boolean parameter - * bool to the target OutputStream. + * Prints the string representation of the specified boolean to the target + * stream. * * @param bool - * the boolean to print on this PrintStream. + * the boolean value to print the target stream. + * @see #print(String) */ public void print(boolean bool) { print(String.valueOf(bool)); } /** - * Prints the String representation of the System property - * "line.separator" to the target OutputStream. - * + * Prints the string representation of the system property + * {@code "line.separator"} to the target stream. */ public void println() { newline(); } /** - * Prints the String representation of the character array parameter - * charArray to the target OutputStream followed by the - * System property "line.separator". + * Prints the string representation of the specified character array + * followed by the system property {@code "line.separator"} to the target + * stream. * * @param charArray - * the character array to print on this PrintStream. + * the character array to print to the target stream. + * @see #print(String) */ public void println(char[] charArray) { println(new String(charArray, 0, charArray.length)); } /** - * Prints the String representation of the character parameter - * ch to the target OutputStream followed by the System - * property "line.separator". + * Prints the string representation of the specified character followed by + * the system property {@code "line.separator"} to the target stream. * * @param ch - * the character to print on this PrintStream. + * the character to print to the target stream. + * @see #print(String) */ public void println(char ch) { println(String.valueOf(ch)); } /** - * Prints the String representation of the double parameter - * dnum to the target OutputStream followed by the System - * property "line.separator". + * Prints the string representation of the specified double followed by the + * system property {@code "line.separator"} to the target stream. * * @param dnum - * the double to print on this PrintStream. + * the double value to print to the target stream. + * @see #print(String) */ public void println(double dnum) { println(String.valueOf(dnum)); } /** - * Prints the String representation of the float parameter - * fnum to the target OutputStream followed by the System - * property "line.separator". + * Prints the string representation of the specified float followed by the + * system property {@code "line.separator"} to the target stream. * * @param fnum - * the float to print on this PrintStream. + * the float value to print to the target stream. + * @see #print(String) */ - public void println(float fnum) { + public void println(float fnum) { println(String.valueOf(fnum)); } - /** - * Obtains the int argument as a String and - * prints it to the target {@link OutputStream} followed by the System - * property "line.separator". + /** + * Prints the string representation of the specified integer followed by the + * system property {@code "line.separator"} to the target stream. * * @param inum - * the int to print on this PrintStream. + * the integer value to print to the target stream. + * @see #print(String) */ public void println(int inum) { println(String.valueOf(inum)); } /** - * Prints the String representation of the long parameter - * lnum to the target OutputStream followed by the System - * property "line.separator". + * Prints the string representation of the specified long followed by the + * system property {@code "line.separator"} to the target stream. * * @param lnum - * the long to print on this PrintStream. + * the long value to print to the target stream. + * @see #print(String) */ public void println(long lnum) { println(String.valueOf(lnum)); } /** - * Prints the String representation of the Object parameter - * obj to the target OutputStream followed by the System - * property "line.separator". + * Prints the string representation of the specified object followed by the + * system property {@code "line.separator"} to the target stream. * * @param obj - * the Object to print on this PrintStream. + * the object to print to the target stream. + * @see #print(String) */ public void println(Object obj) { println(String.valueOf(obj)); } /** - * Prints the String representation of the String parameter - * str to the target OutputStream followed by the System - * property "line.separator". - * + * Prints a string followed by the system property {@code "line.separator"} + * to the target stream. The string is converted to an array of bytes using + * the encoding chosen during the construction of this stream. The bytes are + * then written to the target stream with {@code write(int)}. + *

+ * If an I/O error occurs, this stream's error state is set to {@code true}. + * * @param str - * the String to print on this PrintStream. + * the string to print to the target stream. + * @see #write(int) */ public synchronized void println(String str) { print(str); @@ -610,38 +623,42 @@ } /** - * Prints the String representation of the boolean parameter - * bool to the target OutputStream followed by the System - * property "line.separator". + * Prints the string representation of the specified boolean followed by the + * system property {@code "line.separator"} to the target stream. * * @param bool - * the boolean to print on this PrintStream. + * the boolean value to print to the target stream. + * @see #print(String) */ public void println(boolean bool) { println(String.valueOf(bool)); } + /** + * Sets the error flag of this print stream to {@code true}. + */ protected void setError() { ioError = true; } /** - * Writes count bytes from the byte array - * buffer starting at offset to this - * PrintStream. This implementation writes the buffer to the - * target OutputStream and if this PrintStream is set to autoflush, flushes - * it. If an error occurs, set an error in this PrintStream to - * true. - * + * Writes {@code count} bytes from {@code buffer} starting at {@code offset} + * to the target stream. If autoflush is set, this stream gets flushed after + * writing the buffer. + *

+ * This stream's error flag is set to {@code true} if this stream is closed + * or an I/O error occurs. + * * @param buffer - * the buffer to be written + * the buffer to be written. * @param offset - * offset in buffer to get bytes + * the index of the first byte in {@code buffer} to write. * @param count - * number of bytes in buffer to write - * + * the number of bytes in {@code buffer} 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 bigger than the length of {@code buffer}. + * @see #flush() */ @Override public void write(byte[] buffer, int offset, int count) { @@ -670,12 +687,13 @@ } /** - * Writes the specified byte oneByte to this PrintStream. - * Only the low order byte of oneByte is written. This - * implementation writes oneByte to the target OutputStream. - * If oneByte is equal to the character '\n' - * and this PrintSteam is set to autoflush, the target OutputStream is - * flushed. + * Writes one byte to the target stream. Only the least significant byte of + * the integer {@code oneByte} is written. This stream is flushed if + * {@code oneByte} is equal to the character {@code '\n'} and this stream is + * set to autoflush. + *

+ * This stream's error flag is set to {@code true} if it is closed or an I/O + * error occurs. * * @param oneByte * the byte to be written @@ -697,13 +715,12 @@ } /** - * Append a char c to the PrintStream. The - * PrintStream.append(c) works the same way as - * PrintStream.print(c). + * Appends the character {@code c} to the target stream. This method works + * the same way as {@link #print(char)}. * * @param c - * The character appended to the PrintStream. - * @return The PrintStream. + * the character to append to the target stream. + * @return this stream. */ public PrintStream append(char c) { print(c); @@ -711,15 +728,14 @@ } /** - * Append a CharSequence csq to the PrintStream. The - * PrintStream.append(csq) works the same way as - * PrintStream.print(csq.toString()). If csq - * is null, then a CharSequence just contains then "null" will be - * substituted for csq. + * Appends the character sequence {@code csq} to the target stream. This + * method works the same way as {@code PrintStream.print(csq.toString())}. + * If {@code csq} is {@code null}, then the string "null" is written to the + * target stream. * * @param csq - * The CharSequence appended to the PrintStream. - * @return The PrintStream. + * the character sequence appended to the target stream. + * @return this stream. */ public PrintStream append(CharSequence csq) { if (null == csq) { @@ -731,26 +747,25 @@ } /** - * Append a subsequence of a CharSequence csq to the - * PrintStream. The first char and the last char of the subsequnce is - * specified by the parameter start and end. - * The PrintStream.append(csq) works the same way as - * PrintStream.print (csqcsq.subSequence(start, - * end).toString). If csq is null, then - * "null" will be substituted for csq. + * Appends a subsequence of the character sequence {@code csq} to the target + * stream. This method works the same way as {@code + * PrintStream.print(csq.subsequence(start, end).toString())}. If {@code + * csq} is {@code null}, then the specified subsequence of the string "null" + * will be written to the target stream. * * @param csq - * The CharSequence appended to the PrintStream. + * the character sequence appended to the target stream. * @param start - * The index of the first char in the CharSequence appended to - * the PrintStream. + * the index of the first char in the character sequence appended + * to the target stream. * @param end - * The index of the char after the last one in the CharSequence - * appended to the PrintStream. - * @return The PrintStream. + * the index of the character following the last character of the + * subsequence appended to the target stream. + * @return this stream. * @throws IndexOutOfBoundsException - * If start is less than end, end is greater than the length of - * the CharSequence, or start or end is negative. + * if {@code start > end}, {@code start < 0}, {@code end < 0} or + * either {@code start} or {@code end} are greater or equal than + * the length of {@code csq}. */ public PrintStream append(CharSequence csq, int start, int end) { if (null == csq) {