str.
+ * Construct a new {@code StringBufferInputStream} with {@code str} as
+ * source. The size of the stream is set to the {@code length()} of the
+ * string.
*
* @param str
- * the String to read characters from.
+ * the source string for this stream.
+ * @throws NullPointerException
+ * if {@code str} is {@code null}.
*/
public StringBufferInputStream(String str) {
if (str == null) {
@@ -57,11 +61,10 @@
}
/**
- * Answers an int representing then number of characters that are available
- * to read.
- *
- * @return the number of characters available.
+ * Returns the number of bytes that are available before this stream will
+ * block.
*
+ * @return the number of bytes available before blocking.
*/
@Override
public synchronized int available() {
@@ -69,11 +72,12 @@
}
/**
- * Reads a single byte from this InputStream and returns the result as an
- * int. The low-order byte is returned or -1 of the end of stream was
- * encountered.
+ * Reads a single byte from the source string and returns it as an integer
+ * in the range from 0 to 255. Returns -1 if the end of the source string
+ * has been reached.
*
- * @return the byte read or -1 if end of stream.
+ * @return the byte read or -1 if the end of the source string has been
+ * reached.
*/
@Override
public synchronized int read() {
@@ -81,18 +85,24 @@
}
/**
- * Reads at most length bytes from this InputStream and
- * stores them in byte array b starting at
- * offset. Answer the number of bytes actually read or -1 if
- * no bytes were read and end of stream was encountered.
+ * Reads at most {@code length} bytes from the source string and stores them
+ * in the byte array {@code b} starting at {@code offset}.
*
* @param b
- * the byte array in which to store the read bytes.
+ * the byte array in which to store the bytes read.
* @param offset
- * the offset in b to store the read bytes.
+ * the initial position in {@code b} to store the bytes read from
+ * this stream.
* @param length
- * the maximum number of bytes to store in b.
- * @return the number of bytes actually read or -1 if end of stream.
+ * the maximum number of bytes to store in {@code b}.
+ * @return the number of bytes actually read or -1 if the end of the source
+ * string has been reached.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code length < 0}, or if
+ * {@code offset + length} is greater than the length of
+ * {@code b}.
+ * @throws NullPointerException
+ * if {@code b} is {@code null}.
*/
@Override
public synchronized int read(byte b[], int offset, int length) {
@@ -122,9 +132,7 @@
}
/**
- * Reset this InputStream to position 0. Reads/Skips will now take place
- * from this position.
- *
+ * Resets this stream to the beginning of the source string.
*/
@Override
public synchronized void reset() {
@@ -132,9 +140,10 @@
}
/**
- * Skips count number of characters in this InputStream.
- * Subsequent read()'s will not return these characters
- * unless reset() is used.
+ * Skips {@code n} characters in the source string. It does nothing and
+ * returns 0 if {@code n} is negative. Less than {@code n} characters are
+ * skipped if the end of the source string is reached before the operation
+ * completes.
*
* @param n
* the number of characters to skip.
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java Fri May 1 08:08:59 2009
@@ -20,7 +20,8 @@
import org.apache.harmony.luni.util.Msg;
/**
- * StringReader is used as a character input stream on a String.
+ * A specialized {@link Reader} that reads characters from a {@code String} in
+ * a sequential manner.
*
* @see StringWriter
*/
@@ -34,12 +35,12 @@
private int count;
/**
- * Construct a StringReader on the String str. The size of
- * the reader is set to the length() of the String and the
- * Object to synchronize access through is set to str.
+ * Construct a new {@code StringReader} with {@code str} as source. The size
+ * of the reader is set to the {@code length()} of the string and the Object
+ * to synchronize access through is set to {@code str}.
*
* @param str
- * the String to filter reads on.
+ * the source string for this reader.
*/
public StringReader(String str) {
super();
@@ -48,9 +49,9 @@
}
/**
- * This method closes this StringReader. Once it is closed, you can no
- * longer read from it. Only the first invocation of this method has any
- * effect.
+ * Closes this reader. Once it is closed, read operations on this reader
+ * will throw an {@code IOException}. Only the first invocation of this
+ * method has any effect.
*/
@Override
public void close() {
@@ -58,24 +59,27 @@
}
/**
- * Answer a boolean indicating whether or not this StringReader is closed.
+ * Returns a boolean indicating whether this reader is closed.
*
- * @return true if closed, otherwise false.
+ * @return {@code true} if closed, otherwise {@code false}.
*/
private boolean isClosed() {
return str == null;
}
/**
- * Set a Mark position in this Reader. The parameter readLimit
- * is ignored for StringReaders. Sending reset() will reposition the reader
- * back to the marked position provided the mark has not been invalidated.
+ * Sets a mark position in this reader. The parameter {@code readLimit} is
+ * ignored for this class. Calling {@code reset()} will reposition the
+ * reader back to the marked position.
*
* @param readLimit
- * ignored for StringReaders.
- *
+ * ignored for {@code StringReader} instances.
+ * @throws IllegalArgumentException
+ * if {@code readLimit < 0}.
* @throws IOException
- * If an error occurs attempting mark this StringReader.
+ * if this reader is closed.
+ * @see #markSupported()
+ * @see #reset()
*/
@Override
public void mark(int readLimit) throws IOException {
@@ -92,12 +96,10 @@
}
/**
- * Answers a boolean indicating whether or not this StringReader supports
- * mark() and reset(). This method always returns true.
+ * Indicates whether this reader supports the {@code mark()} and {@code
+ * reset()} methods. This implementation returns {@code true}.
*
- * @return true if mark() and reset() are supported,
- * false otherwise. This implementation always
- * returns true.
+ * @return always {@code true}.
*/
@Override
public boolean markSupported() {
@@ -105,14 +107,14 @@
}
/**
- * Reads a single character from this StringReader and returns the result as
- * an int. The 2 higher-order bytes are set to 0. If the end of reader was
- * encountered then return -1.
- *
- * @return the character read or -1 if end of reader.
+ * Reads a single character from the source string and returns it as an
+ * integer with the two higher-order bytes set to 0. Returns -1 if the end
+ * of the source string has been reached.
*
+ * @return the character read or -1 if the end of the source string has been
+ * reached.
* @throws IOException
- * If the StringReader is already closed.
+ * if this reader is closed.
*/
@Override
public int read() throws IOException {
@@ -127,10 +129,26 @@
}
}
- /*
- * (non-Javadoc)
- *
- * @see java.io.Reader#read(char[], int, int)
+ /**
+ * Reads at most {@code len} characters from the source string and stores
+ * them at {@code offset} in the character array {@code buf}. Returns the
+ * number of characters actually read or -1 if the end of the source string
+ * has been reached.
+ *
+ * @param buf
+ * the character array to store the characters read.
+ * @param offset
+ * the initial position in {@code buffer} to store the characters
+ * read from this reader.
+ * @param len
+ * the maximum number of characters to read.
+ * @return the number of characters read or -1 if the end of the reader has
+ * been reached.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code len < 0}, or if
+ * {@code offset + len} is greater than the size of {@code buf}.
+ * @throws IOException
+ * if this reader is closed.
*/
@Override
public int read(char buf[], int offset, int len) throws IOException {
@@ -158,19 +176,14 @@
}
/**
- * Answers a boolean indicating whether or not this
- * StringReader is ready to be read without blocking. If the result is
- * true, the next read() will not block. If
- * the result is false this Reader may or may not block when
- * read() is sent. The implementation in StringReader always
- * returns true even when it has been closed.
- *
- * @return true if the receiver will not block when
- * read() is called, false if unknown
- * or blocking will occur.
+ * Indicates whether this reader is ready to be read without blocking. This
+ * implementation always returns {@code true}.
*
+ * @return always {@code true}.
* @throws IOException
- * If an IO error occurs.
+ * if this reader is closed.
+ * @see #read()
+ * @see #read(char[], int, int)
*/
@Override
public boolean ready() throws IOException {
@@ -183,13 +196,15 @@
}
/**
- * Reset this StringReader's position to the last mark()
- * location. Invocations of read()/skip() will occur from
- * this new location. If this Reader was not marked, the StringReader is
- * reset to the beginning of the String.
+ * Resets this reader's position to the last {@code mark()} location.
+ * Invocations of {@code read()} and {@code skip()} will occur from this new
+ * location. If this reader has not been marked, it is reset to the
+ * beginning of the source string.
*
* @throws IOException
- * If this StringReader has already been closed.
+ * if this reader is closed.
+ * @see #mark(int)
+ * @see #markSupported()
*/
@Override
public void reset() throws IOException {
@@ -201,10 +216,19 @@
}
}
- /*
- * (non-Javadoc)
- *
- * @see java.io.Reader#skip(long)
+ /**
+ * Skips {@code amount} characters in the source string. Subsequent calls of
+ * {@code read} methods will not return these characters unless {@code
+ * reset()} is used.
+ *
+ * @param ns
+ * the maximum number of characters to skip.
+ * @return the number of characters actually skipped or 0 if {@code ns < 0}.
+ * @throws IOException
+ * if this reader is closed.
+ * @see #mark(int)
+ * @see #markSupported()
+ * @see #reset()
*/
@Override
public long skip(long ns) throws IOException {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java Fri May 1 08:08:59 2009
@@ -18,9 +18,10 @@
package java.io;
/**
- * StringWriter is an class for writing Character Streams to a StringBuffer. The
- * characters written can then be returned as a String. This is used for
- * capturing output sent to a Writer by substituting a StringWriter.
+ * A specialized {@link Writer} that writes characters to a {@code StringBuffer}
+ * in a sequential manner, appending them in the process. The result can later
+ * be queried using the {@link #StringWriter(int)} or {@link #toString()}
+ * methods.
*
* @see StringReader
*/
@@ -29,9 +30,10 @@
private StringBuffer buf;
/**
- * Constructs a new StringWriter which has a StringBuffer allocated with the
- * default size of 16 characters. The StringBuffer is also the
- * lock used to synchronize access to this Writer.
+ * Constructs a new {@code StringWriter} which has a {@link StringBuffer}
+ * allocated with the default size of 16 characters. The {@code
+ * StringBuffer} is also the {@code lock} used to synchronize access to this
+ * writer.
*/
public StringWriter() {
super();
@@ -40,12 +42,13 @@
}
/**
- * Constructs a new StringWriter which has a StringBuffer allocated with the
- * size of initialSize characters. The StringBuffer is also
- * the lock used to synchronize access to this Writer.
+ * Constructs a new {@code StringWriter} which has a {@link StringBuffer}
+ * allocated with a size of {@code initialSize} characters. The {@code
+ * StringBuffer} is also the {@code lock} used to synchronize access to this
+ * writer.
*
* @param initialSize
- * the intial number of characters
+ * the intial size of the target string buffer.
*/
public StringWriter(int initialSize) {
if (initialSize < 0) {
@@ -56,11 +59,12 @@
}
/**
- * Close this Writer. This is the concrete implementation required. This
- * particular implementation does nothing.
+ * Calling this method has no effect. In contrast to most {@code Writer} subclasses,
+ * the other methods in {@code StringWriter} do not throw an {@code IOException} if
+ * {@code close()} has been called.
*
* @throws IOException
- * If an IO error occurs closing this StringWriter.
+ * if an error occurs while closing this writer.
*/
@Override
public void close() throws IOException {
@@ -68,8 +72,7 @@
}
/**
- * Flush this Writer. This is the concrete implementation required. This
- * particular implementation does nothing.
+ * Calling this method has no effect.
*/
@Override
public void flush() {
@@ -77,22 +80,19 @@
}
/**
- * Answer the contents of this StringWriter as a StringBuffer. Any changes
- * made to the StringBuffer by the receiver or the caller are reflected in
- * this StringWriter.
+ * Gets a reference to this writer's internal {@link StringBuffer}. Any
+ * changes made to the returned buffer are reflected in this writer.
*
- * @return this StringWriters local StringBuffer.
+ * @return a reference to this writer's internal {@code StringBuffer}.
*/
public StringBuffer getBuffer() {
return buf;
}
/**
- * Answer the contents of this StringWriter as a String. Any changes made to
- * the StringBuffer by the receiver after returning will not be reflected in
- * the String returned to the caller.
+ * Gets a copy of the contents of this writer as a string.
*
- * @return this StringWriters current contents as a String.
+ * @return this writer's contents as a string.
*/
@Override
public String toString() {
@@ -100,18 +100,18 @@
}
/**
- * Writes count characters starting at offset
- * in cbuf to this StringWriter.
+ * Writes {@code count} characters starting at {@code offset} in {@code buf}
+ * to this writer's {@code StringBuffer}.
*
* @param cbuf
- * the non-null array containing characters to write.
+ * the non-null character array to write.
* @param offset
- * offset in buf to retrieve characters
+ * the index of the first character in {@code cbuf} to write.
* @param count
- * maximum number of characters to write
- *
- * @throws ArrayIndexOutOfBoundsException
- * If offset or count are outside of bounds.
+ * the maximum number of characters to write.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code count < 0}, or if {@code
+ * offset + count} is greater than the size of {@code buf}.
*/
@Override
public void write(char[] cbuf, int offset, int count) {
@@ -127,12 +127,11 @@
}
/**
- * Writes the specified character oneChar to this
- * StringWriter. This implementation writes the low order two bytes to the
- * Stream.
+ * Writes one character to this writer's {@code StringBuffer}. Only the two
+ * least significant bytes of the integer {@code oneChar} are written.
*
* @param oneChar
- * The character to write
+ * the character to write to this writer's {@code StringBuffer}.
*/
@Override
public void write(int oneChar) {
@@ -140,11 +139,11 @@
}
/**
- * Writes the characters from the String str to this
- * StringWriter.
+ * Writes the characters from the specified string to this writer's {@code
+ * StringBuffer}.
*
* @param str
- * the non-null String containing the characters to write.
+ * the non-null string containing the characters to write.
*/
@Override
public void write(String str) {
@@ -152,19 +151,18 @@
}
/**
- * Writes count number of characters starting at
- * offset from the String str to this
- * StringWriter.
+ * Writes {@code count} characters from {@code str} starting at {@code
+ * offset} to this writer's {@code StringBuffer}.
*
* @param str
- * the non-null String containing the characters to write.
+ * the non-null string containing the characters to write.
* @param offset
- * the starting point to retrieve characters.
+ * the index of the first character in {@code str} to write.
* @param count
- * the number of characters to retrieve and write.
- *
- * @throws ArrayIndexOutOfBoundsException
- * If offset or count are outside of bounds.
+ * the number of characters from {@code str} to write.
+ * @throws StringIndexOutOfBoundsException
+ * if {@code offset < 0} or {@code count < 0}, or if {@code
+ * offset + count} is greater than the length of {@code str}.
*/
@Override
public void write(String str, int offset, int count) {
@@ -173,13 +171,12 @@
}
/**
- * Append a char cto the StringWriter. The
- * StringWriter.append(c) works the same way as
- * StringWriter.write(c).
+ * Appends the character {@code c} to this writer's {@code StringBuffer}.
+ * This method works the same way as {@link #write(int)}.
*
* @param c
- * The character appended to the StringWriter.
- * @return The StringWriter.
+ * the character to append to the target stream.
+ * @return this writer.
*/
@Override
public StringWriter append(char c) {
@@ -188,14 +185,14 @@
}
/**
- * Append a CharSequence csq to the StringWriter. The
- * StringWriter.append(csq) works the same way as
- * StringWriter.write(csq.toString()). If csq
- * is null, then "null" will be substituted for csq.
+ * Appends the character sequence {@code csq} to this writer's {@code
+ * StringBuffer}. This method works the same way as {@code
+ * StringWriter.write(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 StringWriter.
- * @return The StringWriter
+ * the character sequence appended to the target.
+ * @return this writer.
*/
@Override
public StringWriter append(CharSequence csq) {
@@ -208,26 +205,25 @@
}
/**
- * Append a subsequence of a CharSequence csq to the
- * StringWriter. The first char and the last char of the subsequnce is
- * specified by the parameter start and end.
- * The StringWriter.append(csq) works the same way as
- * StringWriter.write(csq.subSequence(start,end).toString).If
- * csq is null, then "null" will be substituted for
- * csq. s
+ * Appends a subsequence of the character sequence {@code csq} to this
+ * writer's {@code StringBuffer}. This method works the same way as {@code
+ * StringWriter.writer(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.
*
* @param csq
- * The CharSequence appended to the StringWriter.
+ * the character sequence appended to the target.
* @param start
- * The index of the first char in the CharSequence appended to
- * the StringWriter.
+ * the index of the first char in the character sequence appended
+ * to the target.
* @param end
- * The index of the char after the last one in the CharSequence
- * appended to the StringWriter.
- * @return The StringWriter.
+ * the index of the character following the last character of the
+ * subsequence appended to the target.
+ * @return this writer.
* @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}.
*/
@Override
public StringWriter append(CharSequence csq, int start, int end) {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java Fri May 1 08:08:59 2009
@@ -18,21 +18,19 @@
package java.io;
/**
- * This IO exception is thrown when the method sync() in
- * FileDescriptor failed to complete.
- *
- * @see FileDescriptor#sync()
+ * Signals that the {@link FileDescriptor#sync()} method has failed to
+ * complete.
*/
public class SyncFailedException extends IOException {
private static final long serialVersionUID = -2353342684412443330L;
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
+ * Constructs a new {@code SyncFailedException} with its stack trace and
+ * detail message filled in.
*
* @param detailMessage
- * the detail message for the exception.
+ * the detail message for this exception.
*/
public SyncFailedException(String detailMessage) {
super(detailMessage);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java Fri May 1 08:08:59 2009
@@ -18,8 +18,8 @@
package java.io;
/**
- * This IO exception is thrown when a program attempts to read a UTF-8 String
- * and the encoding is incorrect.
+ * Signals that an incorrectly encoded UTF-8 string has been encountered, most
+ * likely while reading some {@link DataInputStream}.
*
* @see DataInputStream#readUTF()
*/
@@ -28,18 +28,19 @@
private static final long serialVersionUID = 420743449228280612L;
/**
- * Constructs a new instance of this class with its walkback filled in.
+ * Constructs a new {@code UTFDataFormatException} with its stack trace
+ * filled in.
*/
public UTFDataFormatException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
+ * Constructs a new {@code UTFDataFormatException} with its stack trace and
+ * detail message filled in.
*
* @param detailMessage
- * the detail message for the exception.
+ * the detail message for this exception.
*/
public UTFDataFormatException(String detailMessage) {
super(detailMessage);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java Fri May 1 08:08:59 2009
@@ -18,26 +18,27 @@
package java.io;
/**
- * This IO exception is thrown when a program asks for a particular character
- * converter and it is not available.
+ * Thrown when a program asks for a particular character converter that is
+ * unavailable.
*/
public class UnsupportedEncodingException extends IOException {
private static final long serialVersionUID = -4274276298326136670L;
/**
- * Constructs a new instance of this class with its walkback filled in.
+ * Constructs a new {@code UnsupportedEncodingException} with its stack
+ * trace filled in.
*/
public UnsupportedEncodingException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
+ * Constructs a new {@code UnsupportedEncodingException} with its stack
+ * trace and detail message filled in.
*
* @param detailMessage
- * the detail message for the exception.
+ * the detail message for this exception.
*/
public UnsupportedEncodingException(String detailMessage) {
super(detailMessage);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java Fri May 1 08:08:59 2009
@@ -18,9 +18,9 @@
package java.io;
/**
- * This type of exception is thrown by readObject() when it detects an exception
- * marker in the input stream. This marker indicates that when the object was
- * being serialized, an exception happened and this marker was inserted instead
+ * Signals that the {@link ObjectInputStream#readObject()} method has detected
+ * an exception marker in the input stream. This marker indicates that exception
+ * occurred when the object was serialized, and this marker was inserted instead
* of the original object. It is a way to "propagate" an exception from the code
* that attempted to write the object to the code that is attempting to read the
* object.
@@ -32,20 +32,20 @@
private static final long serialVersionUID = -3326426625597282442L;
/**
- * The exception that was caused when writeObject() was attempting to
- * serialize the object
+ * The exception that occured when writeObject() was attempting to serialize
+ * the object.
*/
public Exception detail;
/**
- * Constructs a new instance of this class with its walkback, message and
- * the exception which caused the underlying problem when serializing the
- * object filled in.
+ * Constructs a new {@code WriteAbortedException} with its stack trace,
+ * detail message and the exception which caused the underlying problem when
+ * serializing the object filled in.
*
* @param detailMessage
- * the detail message for the exception.
+ * the detail message for this exception.
* @param rootCause
- * exception that caused the problem when serializing the object.
+ * the exception that was thrown when serializing the object.
*/
public WriteAbortedException(String detailMessage, Exception rootCause) {
super(detailMessage);
@@ -54,11 +54,11 @@
}
/**
- * Answers the extra information message which was provided when the
- * throwable was created. If no message was provided at creation time, then
- * answer null.
+ * Gets the extra information message which was provided when this exception
+ * was created. Returns {@code null} if no message was provided at creation
+ * time.
*
- * @return the receiver's message.
+ * @return the exception message.
*/
@Override
public String getMessage() {
@@ -70,9 +70,9 @@
}
/**
- * Answers the cause of this Throwable, or null if there is no cause.
+ * Gets the cause of this exception or {@code null} if there is no cause.
*
- * @return the receiver's cause.
+ * @return the exception cause.
*/
@Override
public Throwable getCause() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java Fri May 1 08:08:59 2009
@@ -18,9 +18,19 @@
package java.io;
/**
- * Writer is an Abstract class for writing Character Streams. Subclasses of
- * writer must implement the methods write(char[], int, int),
- * close() and flush().
+ * The base class for all writers. A writer is a means of writing data to a
+ * target in a character-wise manner. Most output streams expect the
+ * {@link #flush()} method to be called before closing the stream, to ensure all
+ * data is actually written out.
+ * + * This abstract class does not provide a fully working implementation, so it + * needs to be subclassed, and at least the {@link #write(char[], int, int)}, + * {@link #close()} and {@link #flush()} methods needs to be overridden. + * Overriding some of the non-abstract methods is also often advised, since it + * might result in higher efficiency. + *
+ * Many specialized readers for purposes like reading from a file already exist
+ * in this package.
*
* @see Reader
*/
@@ -34,8 +44,8 @@
protected Object lock;
/**
- * Constructs a new character stream Writer using this as the
- * Object to synchronize critical regions around.
+ * Constructs a new {@code Writer} with {@code this} as the object used to
+ * synchronize critical sections.
*/
protected Writer() {
super();
@@ -43,11 +53,13 @@
}
/**
- * Constructs a new character stream Writer using lock as the
- * Object to synchronize critical regions around.
+ * Constructs a new {@code Writer} with {@code lock} used to synchronize
+ * critical sections.
*
* @param lock
- * the Object to synchronize critical regions around.
+ * the {@code Object} used to synchronize critical sections.
+ * @throws NullPointerException
+ * if {@code lock} is {@code null}.
*/
protected Writer(Object lock) {
if (lock == null) {
@@ -57,63 +69,62 @@
}
/**
- * Close this Writer. This must be implemented by any concrete subclasses.
- * The implementation should free any resources associated with the Writer.
+ * Closes this writer. Implementations of this method should free any
+ * resources associated with the writer.
*
* @throws IOException
- * If an error occurs attempting to close this Writer.
+ * if an error occurs while closing this writer.
*/
public abstract void close() throws IOException;
/**
- * Flush this Writer. This must be implemented by any concrete subclasses.
- * The implementation should ensure all buffered characters are written out.
+ * Flushes this writer. Implementations of this method should ensure that
+ * all buffered characters are written to the target.
*
* @throws IOException
- * If an error occurs attempting to flush this Writer.
+ * if an error occurs while flushing this writer.
*/
public abstract void flush() throws IOException;
/**
- * Writes the entire character buffer buf to this Writer.
+ * Writes the entire character buffer {@code buf} to the target.
*
* @param buf
* the non-null array containing characters to write.
- *
* @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
+ * if this writer is closed or another I/O error occurs.
*/
public void write(char buf[]) throws IOException {
write(buf, 0, buf.length);
}
/**
- * Writes count characters starting at offset in
- * buf to this Writer. This abstract method must be implemented
- * by concrete subclasses.
- *
- * @param buf the non-null array containing characters to write.
- * @param offset offset in buf to retrieve characters
- * @param count maximum number of characters to write
+ * Writes {@code count} characters starting at {@code offset} in {@code buf}
+ * to the target.
*
- * @throws IOException If this Writer has already been closed or some other IOException occurs.
- * @throws ArrayIndexOutOfBoundsException If offset or count are outside of bounds.
+ * @param buf
+ * the non-null character array to write.
+ * @param offset
+ * the index of the first character in {@code buf} to write.
+ * @param count
+ * the maximum number of characters to write.
+ * @throws IndexOutOfBoundsException
+ * 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 is closed or another I/O error occurs.
*/
public abstract void write(char buf[], int offset, int count)
throws IOException;
/**
- * Writes the specified character oneChar to this Writer.
- * This implementation writes the low order two bytes of
- * oneChar to the Stream.
+ * Writes one character to the target. Only the two least significant bytes
+ * of the integer {@code oneChar} are written.
*
* @param oneChar
- * The character to write
- *
+ * the character to write to the target.
* @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
+ * if this writer is closed or another I/O error occurs.
*/
public void write(int oneChar) throws IOException {
synchronized (lock) {
@@ -124,14 +135,12 @@
}
/**
- * Writes the characters from the String str to this Writer.
+ * Writes the characters from the specified string to the target.
*
* @param str
- * the non-null String containing the characters to write.
- *
+ * the non-null string containing the characters to write.
* @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
+ * if this writer is closed or another I/O error occurs.
*/
public void write(String str) throws IOException {
char buf[] = new char[str.length()];
@@ -142,21 +151,20 @@
}
/**
- * Writes count number of characters starting at
- * offset from the String str to this Writer.
+ * Writes {@code count} characters from {@code str} starting at {@code
+ * offset} to the target.
*
* @param str
- * the non-null String containing the characters to write.
+ * the non-null string containing the characters to write.
* @param offset
- * the starting point to retrieve characters.
+ * the index of the first character in {@code str} to write.
* @param count
- * the number of characters to retrieve and write.
- *
+ * the number of characters from {@code str} to write.
* @throws IOException
- * If this Writer has already been closed or some other
- * IOException occurs.
- * @throws ArrayIndexOutOfBoundsException
- * If offset or count are outside of bounds.
+ * if this writer is closed or another I/O error occurs.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code count < 0}, or if {@code
+ * offset + count} is greater than the length of {@code str}.
*/
public void write(String str, int offset, int count) throws IOException {
if (count < 0) { // other cases tested by getChars()
@@ -171,14 +179,14 @@
}
/**
- * Append a char cto the Writer. The Writer.append(c)
- * works the same as Writer.write(c).
+ * Appends the character {@code c} to the target. This method works the same
+ * way as {@link #write(int)}.
*
* @param c
- * The character appended to the Writer.
- * @return The Writer.
+ * the character to append to the target stream.
+ * @return this writer.
* @throws IOException
- * If any IOException raises during the procedure.
+ * if this writer is closed or another I/O error occurs.
*/
public Writer append(char c) throws IOException {
write(c);
@@ -186,16 +194,16 @@
}
/**
- * Append a CharSequence csq to the Writer. The
- * Writer.append(csq) works the same way as Writer.write(csq.toString()).
- * If csq is null, then "null" will be substituted for
- * csq.
+ * Appends the character sequence {@code csq} to the target. This method
+ * works the same way as {@code Writer.write(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 Writer.
- * @return The Writer.
+ * the character sequence appended to the target.
+ * @return this writer.
* @throws IOException
- * If any IOException raises during the procedure.
+ * if this writer is closed or another I/O error occurs.
*/
public Writer append(CharSequence csq) throws IOException {
if (null == csq) {
@@ -207,27 +215,27 @@
}
/**
- * Append a subsequence of a CharSequence csq to the Writer.
- * The first char and the last char of the subsequnce is specified by the
- * parameter start and end. The
- * Writer.append(csq) works the same way as Writer.write (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. This method works the same way as {@code
+ * Writer.writer(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.
*
* @param csq
- * The CharSequence appended to the Writaer.
+ * the character sequence appended to the target.
* @param start
- * The index of the first char in the CharSequence appended to
- * the Writer.
+ * the index of the first char in the character sequence appended
+ * to the target.
* @param end
- * The index of the char after the last one in the CharSequence
- * appended to the Writer.
- * @return The Writer.
- * @throws IndexOutOfBoundsException
- * If start is less than end, end is greater than the length of
- * the CharSequence, or start or end is negative.
+ * the index of the character following the last character of the
+ * subsequence appended to the target.
+ * @return this writer.
* @throws IOException
- * If any IOException raises during the procedure.
+ * if this writer is closed or another I/O error occurs.
+ * @throws IndexOutOfBoundsException
+ * 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 Writer append(CharSequence csq, int start, int end)
throws IOException {