You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/01 10:09:01 UTC
svn commit: r770573 [7/10] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
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 <code>out</code> 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 <code>out</code> as the
- * OutputStream to write converted characters to and <code>enc</code> 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 <code>out</code> as the
- * OutputStream to write converted characters to and <code>cs</code> 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 <code>out</code> as the
- * OutputStream to write converted characters to and <code>enc</code> 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.
* <p>
* 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 <code>null</code> 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 <code>count</code> characters starting at <code>offset</code>
- * in <code>buf</code> 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 <code>oneChar</code> 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 <code>count</code> characters starting at <code>offset</code>
- * in <code>str</code> 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 <code>buffer</code> 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 <code>buffer</code> 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
- * <code>out</code>. 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 <code>out</code> 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.
+ * <p>
+ * 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 <code>count</code> bytes from this PipedInputStream and
- * stores them in byte array <code>buffer</code> starting at
- * <code>offset</code>. Answer the number of bytes actually read or -1 if
- * no bytes were read and end of stream was encountered. 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.
+ * <p>
+ * 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 <code>buffer</code> 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 <code>buffer</code>.
- * @return the number of bytes actually read or -1 if end of stream.
- *
+ * the maximum number of bytes to store in {@code 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 <code>in</code> in the <code>buffer</code>.
- * <P>
- * 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}.
+ * <p>
+ * 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
- * <code>dest</code>. Any data written to this stream can be read from
- * the <code>dest</code>.
+ * 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 <code>dest</code> 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 <code>count</code> <code>bytes</code> from this byte array
- * <code>buffer</code> starting at offset <code>index</code> 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.
+ * <p>
+ * 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 <code>oneByte</code> to this
- * PipedOutputStream. Only the low order byte of <code>oneByte</code> 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.
+ * <p>
+ * 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 <code>buffer</code> 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 <code>buffer</code> 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
- * <code>out</code>. 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 <code>out</code> 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.
+ * <p>
+ * 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 <code>count</code> character from this PipedReader and
- * stores them in char array <code>buffer</code> starting at
- * <code>offset</code>. 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.
+ * <p>
+ * 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 <code>buffer</code> 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
- * <code>buffer</code>.
- * @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 <code>true</code> if there are characters ready,
- * <code>false</code> 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
- * <code>dest</code>. Any data written to this Writer can be read from
- * the <code>dest</code>.
+ * 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 <code>dest</code> 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 <code>count</code> <code>chars</code> from the char array
- * <code>buffer</code> starting at offset <code>index</code> 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.
+ * <p>
+ * 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 <code>c</code> 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.
+ * <p>
+ * 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 <code>out</code>. 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 <code>out</code>. All
- * writes to the target can now take place through this PrintStream. The
- * PrintStream is set to not autoflush if <code>autoflush</code> is
- * <code>true</code>.
+ * 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 <code>out</code>. All
- * writes to the target can now take place through this PrintStream. The
- * PrintStream is set to not autoflush if <code>autoflush</code> is
- * <code>true</code>.
+ * 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 <code>file</code>. 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 <code>file</code>. All writes
- * to the target can now take place through this PrintStream. Its encoding
- * character set name is <code>csn</code>.
+ * 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 is<code>fileName</code>.
- * 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 is<code>fileName</code>.
- * All writes to the target can now take place through this PrintStream. Its
- * encoding character set name is <code>csn</code>.
+ * 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 <code>true</code> if an error occurred in this PrintStream,
- * <code>false</code> 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
- * <code>true</code>.
+ * 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 <code>true</code>.
+ * 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 <code>Formatter</code> to
- * this stream using the given format string and arguments.
- * <p>
- * The method uses the default for the current JVM instance locale, as if it
- * is specified by the <code>Locale.getDefault()</code> 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 <code>Formatter</code> 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 <code>format(String format, Object... args)</code>
- * method.
- * <p>
- * The method uses the default for the current JVM instance locale, as if it
- * is specified by the <code>Locale.getDefault()</code> 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
- * <code>format(Locale l, String format, Object... args)</code> 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
- * <code>charArray</code> 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
- * <code>ch</code> 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 <code>double</code> parameter
- * <code>dnum</code> to the target OutputStream.
+ * Prints the string representation of the specified double to the target
+ * stream.
*
* @param dnum
- * the <code>double</code> 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 <code>float</code> parameter
- * <code>fnum</code> to the target OutputStream.
+ * Prints the string representation of the specified float to the target
+ * stream.
*
* @param fnum
- * the <code>float</code> 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 <code>int</code> argument as a <code>String</code> and
- * prints it to the target {@link OutputStream}.
+ * Prints the string representation of the specified integer to the target
+ * stream.
*
* @param inum
- * the <code>int</code> 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 <code>long</code> parameter
- * <code>lnum</code> to the target OutputStream.
+ * Prints the string representation of the specified long to the target
+ * stream.
*
* @param lnum
- * the <code>long</code> 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 <code>obj</code>
- * 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 <code>String</code> parameter
- * <code>str</code> 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)}.
+ * <p>
+ * If an I/O error occurs, this stream's error state is set to {@code true}.
+ *
* @param str
- * the <code>String</code> 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 <code>boolean</code> parameter
- * <code>bool</code> to the target OutputStream.
+ * Prints the string representation of the specified boolean to the target
+ * stream.
*
* @param bool
- * the <code>boolean</code> 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
- * <code>"line.separator"</code> 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
- * <code>charArray</code> to the target OutputStream followed by the
- * System property <code>"line.separator"</code>.
+ * 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
- * <code>ch</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
+ * 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 <code>double</code> parameter
- * <code>dnum</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
+ * 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 <code>float</code> parameter
- * <code>fnum</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
+ * 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 <code>int</code> argument as a <code>String</code> and
- * prints it to the target {@link OutputStream} followed by the System
- * property <code>"line.separator"</code>.
+ /**
+ * 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 <code>long</code> parameter
- * <code>lnum</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
+ * 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 <code>Object</code> parameter
- * <code>obj</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
+ * Prints the string representation of the specified object followed by the
+ * system property {@code "line.separator"} to the target stream.
*
* @param obj
- * the <code>Object</code> 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 <code>String</code> parameter
- * <code>str</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
- *
+ * 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)}.
+ * <p>
+ * If an I/O error occurs, this stream's error state is set to {@code true}.
+ *
* @param str
- * the <code>String</code> 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 <code>boolean</code> parameter
- * <code>bool</code> to the target OutputStream followed by the System
- * property <code>"line.separator"</code>.
+ * 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 <code>count</code> <code>bytes</code> from the byte array
- * <code>buffer</code> starting at <code>offset</code> to this
- * PrintStream. This implementation writes the <code>buffer</code> 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
- * <code>true</code>.
- *
+ * 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.
+ * <p>
+ * 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 <code>oneByte</code> to this PrintStream.
- * Only the low order byte of <code>oneByte</code> is written. This
- * implementation writes <code>oneByte</code> to the target OutputStream.
- * If <code>oneByte</code> is equal to the character <code>'\n'</code>
- * 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.
+ * <p>
+ * 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 <code>c</code> to the PrintStream. The
- * PrintStream.append(<code>c</code>) works the same way as
- * PrintStream.print(<code>c</code>).
+ * 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 <code>csq</code> to the PrintStream. The
- * PrintStream.append(<code>csq</code>) works the same way as
- * PrintStream.print(<code>csq</code>.toString()). If <code>csq</code>
- * is null, then a CharSequence just contains then "null" will be
- * substituted for <code>csq</code>.
+ * 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 <code>csq</code> to the
- * PrintStream. The first char and the last char of the subsequnce is
- * specified by the parameter <code>start</code> and <code>end</code>.
- * The PrintStream.append(<code>csq</code>) works the same way as
- * PrintStream.print (<code>csq</code>csq.subSequence(<code>start</code>,
- * <code>end</code>).toString). If <code>csq</code> is null, then
- * "null" will be substituted for <code>csq</code>.
+ * 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) {