Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 20316 invoked from network); 1 May 2009 08:09:43 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 1 May 2009 08:09:43 -0000 Received: (qmail 63579 invoked by uid 500); 1 May 2009 08:09:43 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 63518 invoked by uid 500); 1 May 2009 08:09:43 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 63509 invoked by uid 99); 1 May 2009 08:09:42 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:09:42 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 May 2009 08:09:26 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 54BCF2388CE0; Fri, 1 May 2009 08:09:04 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r770573 [4/10] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ Date: Fri, 01 May 2009 08:09:01 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090501080904.54BCF2388CE0@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java Fri May 1 08:08:59 2009 @@ -18,46 +18,48 @@ package java.io; /** - * FileWriter is a class for writing characters out to a file. The default - * character encoding, 8859_1 is currently used to convert characters to bytes - * in the file. + * A specialized {@link Writer} that writes to a file in the file system. + * All write requests made by calling methods in this class are directly + * forwarded to the equivalent function of the underlying operating system. + * Since this may induce some performance penalty, in particular if many small + * write requests are made, a FileWriter is often wrapped by a + * BufferedWriter. * + * @see BufferedWriter * @see FileReader */ public class FileWriter extends OutputStreamWriter { /** - * Creates a FileWriter using the File file. + * Creates a FileWriter using the File {@code file}. * * @param file * the non-null File to write bytes to. - * * @throws IOException - * If the given file is not found + * if {@code file} cannot be opened for writing. */ public FileWriter(File file) throws IOException { super(new FileOutputStream(file)); } /** - * Creates a FileWriter using the File file. The parameter - * append determines whether or not the file is opened and - * appended to or just opened empty. + * Creates a FileWriter using the File {@code file}. The parameter + * {@code append} determines whether or not the file is opened and appended + * to or just opened and overwritten. * * @param file * the non-null File to write bytes to. * @param append - * should the file be appened to or opened empty. - * + * indicates whether or not to append to an existing file. * @throws IOException - * If the given file is not found + * if the {@code file} cannot be opened for writing. */ public FileWriter(File file, boolean append) throws IOException { super(new FileOutputStream(file, append)); } /** - * Creates a FileWriter using the existing FileDescriptor fd. + * Creates a FileWriter using the existing FileDescriptor {@code fd}. * * @param fd * the non-null FileDescriptor to write bytes to. @@ -67,32 +69,28 @@ } /** - * Creates a FileWriter using the platform dependent filename. - * See the class description for how characters are converted to bytes. + * Creates a FileWriter using the platform dependent {@code filename}. * * @param filename * the non-null name of the file to write bytes to. - * * @throws IOException - * If the given file is not found + * if the file cannot be opened for writing. */ public FileWriter(String filename) throws IOException { super(new FileOutputStream(new File(filename))); } /** - * Creates a FileWriter using the platform dependent filename. - * See the class description for how characters are converted to bytes. The - * parameter append determines whether or not the file is - * opened and appended to or just opened empty. + * Creates a FileWriter using the platform dependent {@code filename}. The + * parameter {@code append} determines whether or not the file is opened and + * appended to or just opened and overwritten. * * @param filename * the non-null name of the file to write bytes to. * @param append - * should the file be appened to or opened empty. - * + * indicates whether or not to append to an existing file. * @throws IOException - * If the given file is not found + * if the {@code file} cannot be opened for writing. */ public FileWriter(String filename, boolean append) throws IOException { super(new FileOutputStream(filename, append)); Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java Fri May 1 08:08:59 2009 @@ -18,8 +18,8 @@ package java.io; /** - * FilenameFilter is an interface which declares methods for filtering file - * names in the list method of File. + * An interface for filtering {@link File} objects based on their names + * or the directory they reside in. * * @see File * @see File#list(FilenameFilter) @@ -27,14 +27,15 @@ public interface FilenameFilter { /** - * Answers a boolean if a specific filename matches a filter. + * Indicates if a specific filename matches this filter. * * @param dir - * the directory in which the filename was found. + * the directory in which the {@code filename} was found. * @param filename - * the name of the file in dir to test. - * @return boolean true if the filename matches the filter and can be included - * in the list, false otherwise. + * the name of the file in {@code dir} to test. + * @return {@code true} if the filename matches the filter + * and can be included in the list, {@code false} + * otherwise. */ public abstract boolean accept(File dir, String filename); } Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java Fri May 1 08:08:59 2009 @@ -18,26 +18,28 @@ package java.io; /** - * FilteredInputStream is a class which takes an input stream and - * filters the input in some way. The filtered view may be a buffered - * view or one which uncompresses data before returning bytes read. - * FilterInputStreams are meant for byte streams. + * Wraps an existing {@link InputStream} and performs some transformation on + * the input data while it is being read. Transformations can be anything from a + * simple byte-wise filtering input data to an on-the-fly compression or + * decompression of the underlying stream. Input streams that wrap another input + * stream and provide some additional functionality on top of it usually inherit + * from this class. * * @see FilterOutputStream */ public class FilterInputStream extends InputStream { /** - * The target InputStream which is being filtered. + * The source input stream that is filtered. */ protected volatile InputStream in; /** - * Constructs a new FilterInputStream on the InputStream in. - * All reads are now filtered through this stream. + * Constructs a new {@code FilterInputStream} with the specified input + * stream as source. * * @param in - * The non-null InputStream to filter reads on. + * the non-null InputStream to filter reads on. */ protected FilterInputStream(InputStream in) { super(); @@ -45,14 +47,12 @@ } /** - * Answers a int representing the number of bytes that are available before - * this FilterInputStream will block. This method returns the number of - * bytes available in the target stream. - * + * Returns the number of bytes that are available before this stream will + * block. + * * @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 int available() throws IOException { @@ -60,11 +60,10 @@ } /** - * Close this FilterInputStream. This implementation closes the target - * stream. + * Closes this stream. This implementation closes the filtered stream. * * @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 { @@ -72,17 +71,18 @@ } /** - * Set a Mark position in this FilterInputStream. The parameter - * readLimit indicates how many bytes can be read before a - * mark is invalidated. Sending reset() will reposition the Stream back to - * the marked position provided readLimit has not been - * surpassed. + * Sets a mark position in this stream. The parameter {@code readlimit} + * indicates how many bytes can be read before the mark is invalidated. + * Sending {@code reset()} will reposition this stream back to the marked + * position, provided that {@code readlimit} has not been surpassed. *

- * This implementation sets a mark in the target stream. - * + * This implementation sets a mark in the filtered stream. + * * @param readlimit - * the number of bytes to be able to read before invalidating the - * mark. + * the number of bytes that can be read from this stream before + * the mark is invalidated. + * @see #markSupported() + * @see #reset() */ @Override public synchronized void mark(int readlimit) { @@ -90,12 +90,15 @@ } /** - * Answers a boolean indicating whether or not this FilterInputStream - * supports mark() and reset(). This implementation answers whether or not - * the target stream supports marking. - * - * @return true if mark() and reset() are supported, - * false otherwise. + * Indicates whether this stream supports {@code mark()} and {@code reset()}. + * This implementation returns whether or not the filtered stream supports + * marking. + * + * @return {@code true} if {@code mark()} and {@code reset()} are supported, + * {@code false} otherwise. + * @see #mark(int) + * @see #reset() + * @see #skip(long) */ @Override public boolean markSupported() { @@ -103,15 +106,14 @@ } /** - * Reads a single byte from this FilterInputStream and returns the result as - * an int. The low-order byte is returned or -1 of the end of stream was - * encountered. This implementation returns a byte from the target stream. - * - * @return the byte read or -1 if end of stream. + * Reads a single byte from the filtered 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. * + * @return the byte read or -1 if the end of the filtered stream has been + * reached. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if the stream is closed or another IOException occurs. */ @Override public int read() throws IOException { @@ -119,18 +121,17 @@ } /** - * Reads bytes from this FilterInputStream and stores them in byte array - * buffer. Answer the number of bytes actually read or -1 if - * no bytes were read and end of stream was encountered. This implementation - * reads bytes from the target stream. + * Reads bytes from this stream and stores them in the byte array + * {@code buffer}. Returns the number of bytes actually read or -1 if no + * bytes were read and the end of this stream was encountered. This + * implementation reads bytes from the filtered stream. * * @param buffer * the byte array in which to store the read bytes. - * @return the number of bytes actually read or -1 if end of stream. - * + * @return the number of bytes actually read or -1 if the end of the + * filtered stream has been reached while reading. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. */ @Override public int read(byte[] buffer) throws IOException { @@ -138,23 +139,23 @@ } /** - * Reads at most count bytes from this FilterInputStream and - * stores them in byte array buffer starting at - * offset. Answer the number of bytes actually read or -1 if - * no bytes were read and end of stream was encountered. This implementation - * reads bytes from the target stream. + * Reads at most {@code count} bytes from this stream and stores them in the + * byte array {@code buffer} starting at {@code offset}. Returns the number + * of bytes actually read or -1 if no bytes have been read and the end of + * this stream has been reached. This implementation reads bytes from the + * filtered stream. * * @param buffer - * the byte array in which to store the read bytes. + * the byte array in which to store the bytes read. * @param offset - * the offset in buffer to store the read bytes. + * the initial position in {@code buffer} to store the bytes + * read from this stream. * @param count - * the maximum number of bytes to store in buffer. - * @return the number of bytes actually read or -1 if end of stream. - * + * the maximum number of bytes to store in {@code buffer}. + * @return the number of bytes actually read or -1 if the end of the + * filtered stream has been reached while reading. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another I/O error occurs. */ @Override public int read(byte[] buffer, int offset, int count) throws IOException { @@ -162,14 +163,15 @@ } /** - * Reset this FilterInputStream to the last marked location. If the - * readlimit has been passed or no mark has - * been set, throw IOException. This implementation resets the target - * stream. + * Resets this stream to the last marked location. This implementation + * resets the target stream. * * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is already closed, no mark has been set or the + * mark is no longer valid because more than {@code readlimit} + * bytes have been read since setting the mark. + * @see #mark(int) + * @see #markSupported() */ @Override public synchronized void reset() throws IOException { @@ -177,18 +179,18 @@ } /** - * Skips count number of bytes in this InputStream. - * Subsequent read()'s will not return these bytes unless - * reset() is used. This implementation skips - * count number of bytes in the target stream. + * Skips {@code count} number of bytes in this stream. Subsequent + * {@code read()}'s will not return these bytes unless {@code reset()} is + * used. This implementation skips {@code count} number of bytes in the + * filtered stream. * * @param count * the number of bytes to skip. * @return the number of bytes actually skipped. - * * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. + * @see #mark(int) + * @see #reset() */ @Override public long skip(long count) throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java Fri May 1 08:08:59 2009 @@ -20,37 +20,38 @@ import org.apache.harmony.luni.util.Msg; /** - * FilteredOutputStream is a class which takes an output stream and - * filters the output in some way. The filtered view may be a - * buffered output or one which compresses data before actually writing the - * bytes. FilterOutputStreams are meant for byte streams. + * Wraps an existing {@link OutputStream} and performs some transformation on + * the output data while it is being written. Transformations can be anything + * from a simple byte-wise filtering output data to an on-the-fly compression or + * decompression of the underlying stream. Output streams that wrap another + * output stream and provide some additional functionality on top of it usually + * inherit from this class. * - * @see FilterInputStream + * @see FilterOutputStream */ public class FilterOutputStream extends OutputStream { /** - * The target OutputStream for this filter. + * The target output stream for this filter stream. */ protected OutputStream out; /** - * Constructs a new FilterOutputStream on the OutputStream out. - * All writes are now filtered through this stream. + * Constructs a new {@code FilterOutputStream} with {@code out} as its + * target stream. * * @param out - * the target OutputStream to filter writes on. + * the target stream that this stream writes to. */ public FilterOutputStream(OutputStream out) { this.out = out; } /** - * Close this FilterOutputStream. This implementation closes the target - * stream. + * Closes this stream. This implementation closes the target stream. * * @throws IOException - * If an error occurs attempting to close this stream. + * if an error occurs attempting to close this stream. */ @Override public void close() throws IOException { @@ -64,13 +65,11 @@ } /** - * Flush this FilterOutputStream to ensure all pending data is sent out to - * the target OutputStream. This implementation flushes the target - * OutputStream. + * Ensures that all pending data is sent out to the target stream. This + * implementation flushes the target stream. * * @throws IOException - * If an error occurs attempting to flush this - * FilterOutputStream. + * if an error occurs attempting to flush this stream. */ @Override public void flush() throws IOException { @@ -78,16 +77,14 @@ } /** - * Writes the entire contents of the byte array buffer to - * this FilterOutputStream. This implementation writes the - * buffer to the target stream. + * Writes the entire contents of the byte array {@code buffer} to this + * stream. This implementation writes the {@code buffer} to the target + * stream. * * @param buffer - * the buffer to be written - * + * the buffer to be written. * @throws IOException - * If an error occurs attempting to write to this - * FilterOutputStream. + * if an I/O error occurs while writing to this stream. */ @Override public void write(byte buffer[]) throws IOException { @@ -95,23 +92,21 @@ } /** - * Writes count bytes from the byte array - * buffer starting at offset to this - * FilterOutputStream. This implementation writes the buffer - * to the target OutputStream. + * Writes {@code count} bytes from the byte array {@code buffer} starting at + * {@code offset} to the target stream. * * @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 an error occurs attempting to write to this - * FilterOutputStream. + * 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}. + * @throws IOException + * if an I/O error occurs while writing to this stream. */ @Override public void write(byte buffer[], int offset, int count) throws IOException { @@ -128,16 +123,13 @@ } /** - * Writes the specified byte oneByte to this - * FilterOutputStream. Only the low order byte of oneByte is - * written. This implementation writes the byte to the target OutputStream. + * Writes one byte to the target stream. Only the low order byte of the + * integer {@code oneByte} is written. * * @param oneByte - * the byte to be written - * + * the byte to be written. * @throws IOException - * If an error occurs attempting to write to this - * FilterOutputStream. + * if an I/O error occurs while writing to this stream. */ @Override public void write(int oneByte) throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java Fri May 1 08:08:59 2009 @@ -18,9 +18,12 @@ package java.io; /** - * FilterReader is a class which takes a Reader and filters the input - * in some way. The filtered view may be a buffered view or one which - * uncompresses data before returning characters read. + * Wraps an existing {@link Reader} and performs some transformation on the + * input data while it is being read. Transformations can be anything from a + * simple byte-wise filtering input data to an on-the-fly compression or + * decompression of the underlying reader. Readers that wrap another reader and + * provide some additional functionality on top of it usually inherit from this + * class. * * @see FilterWriter */ @@ -32,8 +35,7 @@ protected Reader in; /** - * Constructs a new FilterReader on the Reader in. All reads - * are now filtered through this Reader. + * Constructs a new FilterReader on the Reader {@code in}. * * @param in * The non-null Reader to filter reads on. @@ -44,10 +46,10 @@ } /** - * Close this FilterReader. This implementation closes the target Reader. + * Closes this reader. This implementation closes the filtered reader. * * @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 { @@ -57,20 +59,20 @@ } /** - * Set a Mark position in this FilterReader. The parameter - * readLimit indicates how many characters can be read before - * a mark is invalidated. Sending reset() will reposition the Reader back to - * the marked position provided readLimit has not been - * surpassed. + * Sets a mark position in this reader. The parameter {@code readlimit} + * indicates how many bytes can be read before the mark is invalidated. + * Sending {@code reset()} will reposition this reader back to the marked + * position, provided that {@code readlimit} has not been surpassed. *

- * This implementation sets a mark in the target Reader. + * This implementation sets a mark in the filtered reader. * * @param readlimit - * the number of characters to be able to read before - * invalidating the mark. - * + * the number of bytes that can be read from this reader before + * the mark is invalidated. * @throws IOException - * If an error occurs attempting mark this Reader. + * if an error occurs while marking this reader. + * @see #markSupported() + * @see #reset() */ @Override public synchronized void mark(int readlimit) throws IOException { @@ -80,11 +82,14 @@ } /** - * Answers a boolean indicating whether or not this FilterReader supports - * mark() and reset(). This implementation answers whether or not the target - * Reader supports marking. + * Indicates whether this reader supports {@code mark()} and {@code reset()}. + * This implementation returns whether the filtered reader supports marking. * - * @return indicates whether or not mark() and reset() are supported. + * @return {@code true} if {@code mark()} and {@code reset()} are supported + * by the filtered reader, {@code false} otherwise. + * @see #mark(int) + * @see #reset() + * @see #skip(long) */ @Override public boolean markSupported() { @@ -94,14 +99,14 @@ } /** - * Reads a single char from this FilterReader and returns the result as an - * int. The 2 lowest order bytes are returned or -1 of the end of reader was - * encountered. This implementation returns a char from the target Reader. - * - * @return The byte read or -1 if end of reader. + * Reads a single character from the filtered reader and returns it as an + * integer with the two higher-order bytes set to 0. Returns -1 if the end + * of the filtered reader has been reached. * + * @return The character read or -1 if the end of the filtered reader has + * been reached. * @throws IOException - * If an error occurs attempting to read from this Reader. + * if an error occurs while reading from this reader. */ @Override public int read() throws IOException { @@ -111,22 +116,22 @@ } /** - * Reads at most count chars from this FilterReader and - * stores them in char array buffer starting at offset - * offset. Answer the number of chars actually read or -1 if - * no chars were read and end of reader was encountered. This implementation - * reads chars from the target reader. + * Reads at most {@code count} characters from the filtered reader and stores them + * in the byte array {@code buffer} starting at {@code offset}. Returns the + * number of characters actually read or -1 if no characters were read and + * the end of the filtered reader was encountered. * * @param buffer - * the char array in which to store the read chars. + * the char array in which to store the characters read. * @param offset - * the offset in buffer to store the read chars. + * the initial position in {@code buffer} to store the characters + * read from this reader. * @param count - * the maximum number of chars to store in buffer. - * @return the number of chars actually read or -1 if end of reader. - * + * the maximum number of characters to store in {@code buffer}. + * @return the number of characters actually read or -1 if the end of the + * filtered reader has been reached while reading. * @throws IOException - * If an error occurs attempting to read from this Reader. + * if an error occurs while reading from this reader. */ @Override public int read(char[] buffer, int offset, int count) throws IOException { @@ -136,19 +141,15 @@ } /** - * Answers a boolean indicating whether or not this Reader is - * ready to be read without blocking. If the result is true, - * the next read() will not block. If the result is - * false this Reader may or may not block when - * read() is sent. - * - * @return true if the receiver will not block when - * read() is called, false if unknown - * or blocking will occur. + * Indicates whether this reader is ready to be read without blocking. If + * the result is {@code true}, the next {@code read()} will not block. If + * the result is {@code false}, this reader may or may not block when + * {@code read()} is sent. * + * @return {@code true} if this reader will not block when {@code read()} + * is called, {@code false} if unknown or blocking will occur. * @throws IOException - * If the Reader is already closed or some other IO error - * occurs. + * if the reader is closed or some other I/O error occurs. */ @Override public boolean ready() throws IOException { @@ -158,16 +159,17 @@ } /** - * Reset this Readers position to the last mark() location. - * Invocations of read()/skip() will occur from this new - * location. If this Reader was not marked, the implementation of - * reset() is implementation specific. See the comment for - * the specific Reader subclass for implementation details. The default - * action is to throw IOException. + * Resets this reader's position to the last marked location. Invocations of + * {@code read()} and {@code skip()} will occur from this new location. If + * this reader was not marked, the behavior depends on the implementation of + * {@code reset()} in the Reader subclass that is filtered by this reader. + * The default behavior for Reader is to throw an {@code IOException}. * * @throws IOException - * if a problem occurred or the target Reader does not support - * mark()/reset(). + * if a problem occurred or the filtered reader does not support + * {@code mark()} and {@code reset()}. + * @see #mark(int) + * @see #markSupported() */ @Override public void reset() throws IOException { @@ -177,18 +179,19 @@ } /** - * Skips count number of characters in this Reader. - * Subsequent read()'s will not return these characters - * unless reset() is used. The default implementation is to - * skip chars in the filtered Reader. + * Skips {@code count} characters in this reader. Subsequent {@code read()}'s + * will not return these characters unless {@code reset()} is used. The + * default implementation is to skip characters in the filtered reader. * * @param count * the maximum number of characters to skip. * @return the number of characters actually skipped. - * * @throws IOException - * If the Reader is already closed or some other IO error + * if the filtered reader is closed or some other I/O error * occurs. + * @see #mark(int) + * @see #markSupported() + * @see #reset() */ @Override public long skip(long count) throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java Fri May 1 08:08:59 2009 @@ -18,11 +18,14 @@ package java.io; /** - * FilterWriter is a class which takes a Writer and filters the - * output in some way. The filtered view may be a buffered output or one which - * compresses data before actually writing the bytes. + * Wraps an existing {@link Writer} and performs some transformation on the + * output data while it is being written. Transformations can be anything from a + * simple byte-wise filtering output data to an on-the-fly compression or + * decompression of the underlying writer. Writers that wrap another writer and + * provide some additional functionality on top of it usually inherit from this + * class. * - * @see FilterWriter + * @see FilterReader */ public abstract class FilterWriter extends Writer { @@ -32,8 +35,8 @@ protected Writer out; /** - * Constructs a new FilterWriter on the Writer out. All - * writes are now filtered through this Writer. + * Constructs a new FilterWriter on the Writer {@code out}. All writes are + * now filtered through this writer. * * @param out * the target Writer to filter writes on. @@ -44,13 +47,10 @@ } /** - * Close this FilterWriter. Closes the Writer out by default. - * This will close any downstream Writers as well. Any additional processing - * required by concrete subclasses should be provided in their own - * close implementation. + * Closes this writer. This implementation closes the target writer. * - * @throws java.io.IOException - * If an error occurs attempting to close this FilterWriter. + * @throws IOException + * if an error occurs attempting to close this writer. */ @Override public void close() throws IOException { @@ -60,11 +60,11 @@ } /** - * Flush this FilteredWriter to ensure all pending data is sent out to the - * target Writer. This implementation flushes the target Writer. + * Flushes this writer to ensure all pending data is sent out to the target + * writer. This implementation flushes the target writer. * - * @throws java.io.IOException - * If an error occurs attempting to flush this FilterWriter. + * @throws IOException + * if an error occurs attempting to flush this writer. */ @Override public void flush() throws IOException { @@ -74,20 +74,17 @@ } /** - * Writes count chars from the char array - * buffer starting at offset index to this - * FilterWriter. This implementation writes the buffer to the - * target Writer. + * Writes {@code count} characters from the char array {@code buffer} + * starting at position {@code offset} to the target writer. * * @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 an error occurs attempting to write to this FilterWriter. + * the number of characters in {@code buffer} to write. + * @throws IOException + * if an error occurs while writing to this writer. */ @Override public void write(char buffer[], int offset, int count) throws IOException { @@ -97,15 +94,13 @@ } /** - * Writes the specified char oneChar to this FilterWriter. - * Only the 2 low order bytes of oneChar is written. This - * implementation writes the char to the target Writer. + * Writes the specified character {@code oneChar} to the target writer. Only the + * two least significant bytes of the integer {@code oneChar} are written. * * @param oneChar - * the char to be written - * - * @throws java.io.IOException - * If an error occurs attempting to write to this FilterWriter. + * the char to write to the target writer. + * @throws IOException + * if an error occurs while writing to this writer. */ @Override public void write(int oneChar) throws IOException { @@ -115,20 +110,18 @@ } /** - * Writes count chars from the String - * str starting at offset index to this - * FilterWriter. This implementation writes the str to the - * target Writer. + * Writes {@code count} characters from the string {@code str} starting at + * position {@code index} to this writer. This implementation writes + * {@code str} to the target writer. * * @param str - * the String to be written. + * the string to be written. * @param offset - * offset in str to get chars. + * the index of the first character in {@code str} to write. * @param count - * number of chars in str to write. - * - * @throws java.io.IOException - * If an error occurs attempting to write to this FilterWriter. + * the number of chars in {@code str} to write. + * @throws IOException + * if an error occurs while writing to this writer. */ @Override public void write(String str, int offset, int count) throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java Fri May 1 08:08:59 2009 @@ -17,19 +17,15 @@ package java.io; /** - *

- * Indicates that an output object can be flushed. - *

- * - * @since 1.5 + * Defines an interface for classes that can (or need to) be flushed, typically + * before some output processing is considered to be finished and the object + * gets closed. */ public interface Flushable { /** - *

* Flushes the object by writing out any buffered data to the underlying * output. - *

- * + * * @throws IOException * if there are any issues writing the data. */ Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java Fri May 1 08:08:59 2009 @@ -18,26 +18,28 @@ package java.io; /** - * This IO exception is thrown when a program encounters some sort I/O error. - * Details may be specified in the constructor or by one of the subclasses. + * Signals a general, I/O-related error. Error details may be specified when + * calling the constructor, as usual. Note there are also several subclasses of + * this class for more specific error situations, such as + * {@link FileNotFoundException} or {@link EOFException}. */ public class IOException extends Exception { private static final long serialVersionUID = 7818375828146090155L; /** - * Constructs a new instance of this class with its walkback filled in. + * Constructs a new {@code IOException} with its stack trace filled in. */ public IOException() { super(); } /** - * Constructs a new instance of this class with its walkback and message - * filled in. + * Constructs a new {@code IOException} with its stack trace and detail + * message filled in. * * @param detailMessage - * The detail message for the exception. + * the detail message for this exception. */ public IOException(String detailMessage) { super(detailMessage); Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java Fri May 1 08:08:59 2009 @@ -18,8 +18,18 @@ package java.io; /** - * InputStream is an abstract class for all byte input streams. It provides - * basic method implementations for reading bytes from a stream. + * The base class for all input streams. An input stream is a means of reading + * data from a source in a byte-wise manner. + *

+ * Some input streams also support marking a position in the input stream and + * returning to this position later. This abstract class does not provide a + * fully working implementation, so it needs to be subclassed, and at least the + * {@link #read()} method needs to be overridden. Overriding some of the + * non-abstract methods is also often advised, since it might result in higher + * efficiency. + *

+ * Many specialized input streams for purposes like reading from a file already + * exist in this package. * * @see OutputStream */ @@ -28,7 +38,7 @@ private static byte[] skipBuf; /** - * This constructor does nothing interesting. Provided for signature + * This constructor does nothing. It is provided for signature * compatibility. */ public InputStream() { @@ -36,108 +46,105 @@ } /** - * Answers a int representing then number of bytes that are available before - * this InputStream will block. This method always returns 0. Subclasses - * should override and indicate the correct number of bytes available. + * Returns the number of bytes that are available before this stream will + * block. This implementation always returns 0. Subclasses should override + * and indicate the correct number of bytes available. * * @return the number of bytes available before blocking. - * * @throws IOException - * If an error occurs in this InputStream. + * if an error occurs in this stream. */ public int available() throws IOException { return 0; } /** - * Close the InputStream. Concrete implementations of this class should free + * Closes this stream. Concrete implementations of this class should free * any resources during close. This implementation does nothing. * * @throws IOException - * If an error occurs attempting to close this InputStream. + * if an error occurs while closing this stream. */ public void close() throws IOException { /* empty */ } /** - * Set a Mark position in this InputStream. The parameter - * readLimit indicates how many bytes can be read before a - * mark is invalidated. Sending reset() will reposition the Stream back to - * the marked position provided readLimit has not been - * surpassed. + * Sets a mark position in this InputStream. The parameter {@code readlimit} + * indicates how many bytes can be read before the mark is invalidated. + * Sending {@code reset()} will reposition the stream back to the marked + * position provided {@code readLimit} has not been surpassed. *

* This default implementation does nothing and concrete subclasses must - * provide their own implementations. - * + * provide their own implementation. + * * @param readlimit - * the number of bytes to be able to read before invalidating the - * mark. + * the number of bytes that can be read from this stream before + * the mark is invalidated. + * @see #markSupported() + * @see #reset() */ public void mark(int readlimit) { /* empty */ } /** - * Answers a boolean indicating whether or not this InputStream supports - * mark() and reset(). This class provides a default implementation which - * answers false. + * Indicates whether this stream supports the {@code mark()} and + * {@code reset()} methods. The default implementation returns {@code false}. * - * @return true if mark() and reset() are supported, - * false otherwise. + * @return always {@code false}. + * @see #mark(int) + * @see #reset() */ public boolean markSupported() { return false; } /** - * 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. This abstract implementation must be provided by concrete - * subclasses. - * - * @return the byte read or -1 if end of stream. + * Reads a single byte from this stream and returns it as an integer in the + * range from 0 to 255. Returns -1 if the end of the stream has been + * reached. Blocks until one byte has been read, the end of the source + * stream is detected or an exception is thrown. * + * @return the byte read or -1 if the end of stream has been reached. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if the stream is closed or another IOException occurs. */ public abstract int read() throws IOException; /** - * Reads bytes from the Stream and stores them in byte array b. - * Answer the number of bytes actually read or -1 if no bytes were read and - * end of stream was encountered. + * Reads bytes from this stream and stores them in the byte array {@code b}. * * @param b - * the byte array in which to store the read bytes. - * @return the number of bytes actually read or -1 if end of stream. - * + * the byte array in which to store the bytes read. + * @return the number of bytes actually read or -1 if the end of the stream + * has been reached. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. */ public int read(byte b[]) throws IOException { return read(b, 0, b.length); } /** - * Reads at most length bytes from the Stream 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 this stream 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 buffer} 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 stream + * 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 IOException - * If the stream is already closed or another IOException - * occurs. + * if the stream is closed or another IOException occurs. */ public int read(byte b[], int offset, int length) throws IOException { // avoid int overflow, check null b @@ -163,34 +170,34 @@ } /** - * Reset this InputStream to the last marked location. If the - * readlimit has been passed or no mark has - * been set, throw IOException. This implementation throws IOException and - * concrete subclasses should provide proper implementations. - * + * Resets this stream to the last marked location. Throws an + * {@code IOException} if the number of bytes read since the mark has been + * set is greater than the limit provided to {@code mark}, or if no mark + * has been set. + *

+ * This implementation always throws an {@code IOException} and concrete + * subclasses should provide the proper implementation. + * * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. */ public synchronized void reset() throws IOException { throw new IOException(); } /** - * Skips n number of bytes in this InputStream. Subsequent - * read()'s will not return these bytes unless - * reset() is used. This method may perform multiple reads to - * read n bytes. This default implementation reads - * n bytes into a temporary buffer. Concrete subclasses - * should provide their own implementation. - * + * Skips at most {@code n} bytes in this stream. It does nothing and returns + * 0 if {@code n} is negative. Less than {@code n} characters are skipped if + * the end of this stream is reached before the operation completes. + *

+ * This default implementation reads {@code n} bytes into a temporary + * buffer. Concrete subclasses should provide their own implementation. + * * @param n * the number of bytes to skip. * @return the number of bytes actually skipped. - * * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. */ public long skip(long n) throws IOException { if (n <= 0) { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java Fri May 1 08:08:59 2009 @@ -32,12 +32,12 @@ import org.apache.harmony.luni.util.PriviAction; /** - * InputStreamReader is class for turning a byte Stream into a character Stream. - * Data read from the source input stream is converted into characters by either - * a default or provided character converter. By default, the encoding is - * assumed to ISO8859_1. The InputStreamReader contains a buffer of bytes read - * from the source input stream and converts these into characters as needed. - * The buffer size is 8K. + * A class for turning a byte stream into a character stream. Data read from the + * source input stream is converted into characters by either a default or a + * provided character converter. The default encoding is taken from the + * "file.encoding" system property. {@code InputStreamReader} contains a buffer + * of bytes read from the source stream and converts these into characters as + * needed. The buffer size is 8K. * * @see OutputStreamWriter */ @@ -53,13 +53,13 @@ ByteBuffer bytes = ByteBuffer.allocate(BUFFER_SIZE); /** - * Constructs a new InputStreamReader on the InputStream in. - * Now character reading can be filtered through this InputStreamReader. - * This constructor assumes the default conversion of ISO8859_1 - * (ISO-Latin-1). + * Constructs a new {@code InputStreamReader} on the {@link InputStream} + * {@code in}. This constructor sets the character converter to the encoding + * specified in the "file.encoding" property and falls back to ISO 8859_1 + * (ISO-Latin-1) if the property doesn't exist. * * @param in - * the InputStream to convert to characters. + * the input stream from which to read characters. */ public InputStreamReader(InputStream in) { super(in); @@ -74,19 +74,19 @@ } /** - * Constructs a new InputStreamReader on the InputStream in. - * Now character reading can be filtered through this InputStreamReader. - * This constructor takes a String parameter enc which is the - * name of an encoding. If the encoding cannot be found, an + * Constructs a new InputStreamReader on the InputStream {@code in}. The + * character converter that is used to decode bytes into characters is + * identified by name by {@code enc}. If the encoding cannot be found, an * UnsupportedEncodingException error is thrown. * * @param in - * the InputStream to convert to characters. + * the InputStream from which to read characters. * @param enc - * a String describing the character converter to use. - * + * identifies the character converter to use. + * @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 InputStreamReader(InputStream in, final String enc) throws UnsupportedEncodingException { @@ -107,14 +107,13 @@ } /** - * Constructs a new InputStreamReader on the InputStream in - * and CharsetDecoder dec. Now character reading can be - * filtered through this InputStreamReader. + * Constructs a new InputStreamReader on the InputStream {@code in} and + * CharsetDecoder {@code dec}. * * @param in - * the InputStream to convert to characters + * the source InputStream from which to read characters. * @param dec - * a CharsetDecoder used by the character conversion + * the CharsetDecoder used by the character conversion. */ public InputStreamReader(InputStream in, CharsetDecoder dec) { super(in); @@ -125,14 +124,13 @@ } /** - * Constructs a new InputStreamReader on the InputStream in - * and Charset charset. Now character reading can be - * filtered through this InputStreamReader. + * Constructs a new InputStreamReader on the InputStream {@code in} and + * Charset {@code charset}. * * @param in - * the InputStream to convert to characters + * the source InputStream from which to read characters. * @param charset - * the Charset that specify the character converter + * the Charset that defines the character converter */ public InputStreamReader(InputStream in, Charset charset) { super(in); @@ -144,12 +142,11 @@ } /** - * Close this InputStreamReader. This implementation closes the source - * InputStream and releases all local storage. + * Closes this reader. This implementation closes the source InputStream and + * releases all local storage. * * @throws IOException - * If an error occurs attempting to close this - * InputStreamReader. + * if an error occurs attempting to close this reader. */ @Override public void close() throws IOException { @@ -163,12 +160,11 @@ } /** - * Answer the String which identifies the encoding used to convert bytes to - * characters. The value null is returned if this Reader has - * been closed. + * Returns the name of the encoding used to convert bytes into characters. + * The value {@code null} is returned if this reader has been closed. * - * @return the String describing the converter or null if this Reader is - * closed. + * @return the name of the character converter or {@code null} if this + * reader is closed. */ public String getEncoding() { if (!isOpen()) { @@ -178,17 +174,16 @@ } /** - * Reads a single character from this InputStreamReader and returns the - * result as an int. The 2 higher-order characters are set to 0. If the end - * of reader was encountered then return -1. The byte value is either - * obtained from converting bytes in this readers buffer or by first filling - * the buffer from the source InputStream and then reading from the buffer. - * - * @return the character read or -1 if end of reader. + * Reads a single character from this reader and returns it as an integer + * with the two higher-order bytes set to 0. Returns -1 if the end of the + * reader has been reached. The byte value is either obtained from + * converting bytes in this reader's buffer or by first filling the buffer + * from the source InputStream and then reading from the buffer. * + * @return the character read or -1 if the end of the reader has been + * reached. * @throws IOException - * If the InputStreamReader is already closed or some other IO - * error occurs. + * if this reader is closed or some other I/O error occurs. */ @Override public int read() throws IOException { @@ -204,24 +199,28 @@ } /** - * Reads at most count characters from this Reader and stores - * them at offset in the character array buf. - * Returns the number of characters actually read or -1 if the end of reader - * was encountered. The bytes are either obtained from converting bytes in - * this readers buffer or by first filling the buffer from the source + * Reads at most {@code length} characters from this reader and stores them + * at position {@code offset} in the character array {@code buf}. Returns + * the number of characters actually read or -1 if the end of the reader has + * been reached. The bytes are either obtained from converting bytes in this + * reader's buffer or by first filling the buffer from the source * InputStream and then reading from the buffer. * * @param buf - * character array to store the read characters + * the array to store the characters read. * @param offset - * offset in buf to store the read characters + * the initial position in {@code buf} to store the characters + * read from this reader. * @param length - * maximum number of characters to read - * @return the number of characters read or -1 if end of reader. - * + * 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 length < 0}, or if + * {@code offset + length} is greater than the length of + * {@code buf}. * @throws IOException - * If the InputStreamReader is already closed or some other IO - * error occurs. + * if this reader is closed or some other I/O error occurs. */ @Override public int read(char[] buf, int offset, int length) throws IOException { @@ -306,21 +305,17 @@ } /** - * Answers a boolean indicating whether or not this - * InputStreamReader 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. This implementation answers - * true if there are bytes available in the buffer or the - * source InputStream has bytes available. - * - * @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. If + * the result is {@code true}, the next {@code read()} will not block. If + * the result is {@code false} then this reader may or may not block when + * {@code read()} is called. This implementation returns {@code true} if + * there are bytes available in the buffer or the source stream has bytes + * available. * + * @return {@code true} if the receiver will not block when {@code read()} + * is called, {@code false} if unknown or blocking will occur. * @throws IOException - * If the InputStreamReader is already closed or some other IO - * error occurs. + * if this reader is closed or some other I/O error occurs. */ @Override public boolean ready() throws IOException { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java Fri May 1 08:08:59 2009 @@ -18,34 +18,33 @@ package java.io; /** - * This IO exception is thrown when a program reading or writing to a stream is - * interrupted. This is also thrown when a socket timeout occurs before the - * request has completed. + * Signals that a blocking I/O operation has been interrupted. The number of + * bytes that were transferred successfully before the interruption took place + * is stored in a field of the exception. */ public class InterruptedIOException extends IOException { private static final long serialVersionUID = 4020568460727500567L; /** - * The number of bytes transferred before the IO interrupt occurred. The - * default is 0 but the value may be filled in by the caller of the - * constructor. + * The number of bytes transferred before the I/O interrupt occurred. */ public int bytesTransferred; /** - * Constructs a new instance of this class with its walkback filled in. + * Constructs a new {@code InterruptedIOException} with its stack trace + * filled in. */ public InterruptedIOException() { super(); } /** - * Constructs a new instance of this class with its walkback and message - * filled in. + * Constructs a new {@code InterruptedIOException} with its stack trace and + * detail message filled in. * * @param detailMessage - * The detail message for the exception. + * the detail message for this exception. */ public InterruptedIOException(String detailMessage) { super(detailMessage); Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java Fri May 1 08:08:59 2009 @@ -18,13 +18,13 @@ package java.io; /** - * A problem was found with the class of one of the objects being serialized or - * deserialized. These can be + * Signals a problem during the serialization or or deserialization of an + * object. Possible reasons include: *

    *
  • The SUIDs of the class loaded by the VM and the serialized class info do - * not match
    • + * not match. *
  • A serializable or externalizable object cannot be instantiated (when - * deserializing) because the empty constructor that needs to be run is not + * deserializing) because the no-arg constructor that needs to be run is not * visible or fails.
    • *
* @@ -36,30 +36,30 @@ private static final long serialVersionUID = -4333316296251054416L; /** - * The fully qualified name of the class that caused the problem + * The fully qualified name of the class that caused the problem. */ public String classname; /** - * Constructs a new instance of this class with its walkback and message - * filled in. + * Constructs a new {@code InvalidClassException} with its stack trace and + * detailed message filled in. * * @param detailMessage - * The detail message for the exception. + * the detail message for this exception. */ public InvalidClassException(String detailMessage) { super(detailMessage); } /** - * Constructs a new instance of this class with its walkback, message and - * the fully qualified name of the class which caused the exception filled - * in. + * Constructs a new {@code InvalidClassException} with its stack trace, + * detail message and the fully qualified name of the class which caused the + * exception filled in. * * @param className - * The detail message for the exception. + * the name of the class that caused the exception. * @param detailMessage - * The detail message for the exception. + * the detail message for this exception. */ public InvalidClassException(String className, String detailMessage) { super(detailMessage); @@ -67,13 +67,13 @@ } /** - * Answers the extra information message which was provided when the - * exception was created. If no message was provided at creation time, then - * answer null. If a message was provided and a class name which caused the - * exception, the values are concatenated and returned. + * Returns the detail message which was provided when the exception was + * created. {@code null} is returned if no message was provided at creation + * time. If a detail message as well as a class name are provided, then the + * values are concatenated and returned. * - * @return The receiver's message, possibly concatenated with the name of - * the class that caused the problem. + * @return the detail message, possibly concatenated with the name of the + * class that caused the problem. */ @Override public String getMessage() { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java Fri May 1 08:08:59 2009 @@ -18,9 +18,7 @@ package java.io; /** - * The object graph loaded (deserialized) can be validated by a collection of - * validator objects. If these decide the validation fails, then will throw - * InvalidObjectException. + * Signals that, during deserialization, the validation of an object has failed. * * @see ObjectInputStream#registerValidation(ObjectInputValidation, int) * @see ObjectInputValidation#validateObject() @@ -30,11 +28,11 @@ private static final long serialVersionUID = 3233174318281839583L; /** - * Constructs a new instance of this class with its walkback and message - * filled in. + * Constructs an {@code InvalidObjectException} with its stack trace and + * detail message filled in. * * @param detailMessage - * The detail message for the exception. + * the detail message for this exception. */ public InvalidObjectException(String detailMessage) { super(detailMessage); Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java?rev=770573&r1=770572&r2=770573&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java Fri May 1 08:08:59 2009 @@ -18,12 +18,13 @@ package java.io; /** - * LineNumberInputStream is a filter class which counts the number of line - * terminators from the data read from the target InputStream. A line delimiter - * sequence is determined by '\r', '\n', or '\r\n'. When using read, - * the sequence is always translated into '\n'. + * Wraps an existing {@link InputStream} and counts the line terminators + * encountered while reading the data. Line numbering starts at 0. Recognized + * line terminator sequences are {@code '\r'}, {@code '\n'} and {@code "\r\n"}. + * When using {@code read}, line terminator sequences are always translated into + * {@code '\n'}. * - * @deprecated Use LineNumberReader + * @deprecated Use {@link LineNumberReader} */ @Deprecated public class LineNumberInputStream extends FilterInputStream { @@ -37,28 +38,28 @@ private int markedLastChar; /** - * Constructs a new LineNumberInputStream on the InputStream in. - * All reads are now filtered through this stream and line numbers will be - * counted for all data read from this Stream. + * Constructs a new {@code LineNumberInputStream} on the {@link InputStream} + * {@code in}. Line numbers are counted for all data read from this stream. * * @param in - * The non-null InputStream to count line numbers. + * The non-null input stream to count line numbers. */ public LineNumberInputStream(InputStream in) { super(in); } /** - * Answers a int representing the number of bytes that are available before - * this LineNumberInputStream will block. This method returns the number of - * bytes available in the target stream. Since the target input stream may - * just be a sequence of \r\n characters and this filter only - * returns \n then available can only - * guarantee target.available()/2 characters. - * - * @return int the number of bytes available before blocking. + * Returns the number of bytes that are available before this stream will + * block. + *

+ * Note: The source stream may just be a sequence of {@code "\r\n"} bytes + * which are converted into {@code '\n'} by this stream. Therefore, + * {@code available} returns only {@code in.available() / 2} bytes as + * result. * - * @throws IOException If an error occurs in this stream. + * @return the guaranteed number of bytes available before blocking. + * @throws IOException + * if an error occurs in this stream. */ @Override public int available() throws IOException { @@ -66,28 +67,29 @@ } /** - * Answers a int representing the current line number for this - * LineNumberInputStream. + * Returns the current line number for this stream. Numbering starts at 0. * - * @return int the current line number. + * @return the current line number. */ public int getLineNumber() { return lineNumber; } /** - * Set a Mark position in this LineNumberInputStream. The parameter - * readLimit indicates how many bytes can be read before a - * mark is invalidated. Sending reset() will reposition the Stream back to - * the marked position provided readLimit has not been - * surpassed. The lineNumber count will also be reset to the last marked - * lineNumber count. + * Sets a mark position in this stream. The parameter {@code readlimit} + * indicates how many bytes can be read before the mark is invalidated. + * Sending {@code reset()} will reposition this stream back to the marked + * position, provided that {@code readlimit} has not been surpassed. + * The line number count will also be reset to the last marked + * line number count. *

- * This implementation sets a mark in the target stream. - * + * This implementation sets a mark in the filtered stream. + * * @param readlimit - * The number of bytes to be able to read before invalidating the - * mark. + * the number of bytes that can be read from this stream before + * the mark is invalidated. + * @see #markSupported() + * @see #reset() */ @Override public void mark(int readlimit) { @@ -97,18 +99,19 @@ } /** - * Reads a single byte from this LineNumberInputStream and returns the - * result as an int. The low-order byte is returned or -1 of the end of - * stream was encountered. This implementation returns a byte from the - * target stream. The line number count is incremented if a line terminator - * is encountered. A line delimiter sequence is determined by '\r', '\n', or - * '\r\n'. In this method, the sequence is always translated into '\n'. - * - * @return int The byte read or -1 if end of stream. - * + * Reads a single byte from the filtered 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. + *

+ * The line number count is incremented if a line terminator is encountered. + * Recognized line terminator sequences are {@code '\r'}, {@code '\n'} and + * {@code "\r\n"}. Line terminator sequences are always translated into + * {@code '\n'}. + * + * @return the byte read or -1 if the end of the filtered stream has been + * reached. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if the stream is closed or another IOException occurs. */ @SuppressWarnings("fallthrough") @Override @@ -134,31 +137,33 @@ } /** - * Reads at most length bytes from this LineNumberInputStream - * and stores them in byte array buffer starting at - * offset. Answer the number of bytes actually read or -1 if - * no bytes were read and end of stream was encountered. This implementation - * reads bytes from the target stream. The line number count is incremented - * if a line terminator is encountered. A line delimiter sequence is - * determined by '\r', '\n', or '\r\n'. In this method, the sequence is - * always translated into '\n'. - * + * Reads at most {@code length} bytes from the filtered stream and stores + * them in the byte array {@code buffer} starting at {@code offset}. + * Returns the number of bytes actually read or -1 if no bytes have been + * read and the end of this stream has been reached. + *

+ * The line number count is incremented if a line terminator is encountered. + * Recognized line terminator sequences are {@code '\r'}, {@code '\n'} and + * {@code "\r\n"}. Line terminator sequences are always translated into + * {@code '\n'}. + * * @param buffer - * the non-null byte array in which to store the read bytes. + * the array in which to store the bytes read. * @param offset - * the offset in buffer to store the read bytes. + * the initial position in {@code buffer} to store the bytes read + * from this stream. * @param length - * the maximum number of bytes to store in buffer. - * @return The number of bytes actually read or -1 if end of stream. - * + * the maximum number of bytes to store in {@code buffer}. + * @return the number of bytes actually read or -1 if the end of the + * filtered stream has been reached while reading. + * @throws IndexOutOfBoundsException + * if {@code offset < 0} or {@code length < 0}, or if + * {@code offset + length} is greater than the length of + * {@code buffer}. * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. * @throws NullPointerException - * If buffer is null. - * @throws IllegalArgumentException - * If offset or count are out of - * bounds. + * if {@code buffer} is {@code null}. */ @Override public int read(byte[] buffer, int offset, int length) throws IOException { @@ -190,15 +195,15 @@ } /** - * Reset this LineNumberInputStream to the last marked location. If the - * readlimit has been passed or no mark has - * been set, throw IOException. This implementation resets the target - * stream. It also resets the line count to what is was when this Stream was - * marked. + * Resets this stream to the last marked location. It also resets the line + * count to what is was when this stream was marked. * * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is already closed, no mark has been set or the + * mark is no longer valid because more than {@code readlimit} + * bytes have been read since setting the mark. + * @see #mark(int) + * @see #markSupported() */ @Override public void reset() throws IOException { @@ -208,31 +213,34 @@ } /** - * Sets the lineNumber of this LineNumberInputStream to the specified - * lineNumber. Note that this may have side effects on the + * Sets the line number of this stream to the specified + * {@code lineNumber}. Note that this may have side effects on the * line number associated with the last marked position. * * @param lineNumber * the new lineNumber value. + * @see #mark(int) + * @see #reset() */ public void setLineNumber(int lineNumber) { this.lineNumber = lineNumber; } /** - * Skips count number of bytes in this InputStream. - * Subsequent read()'s will not return these bytes unless - * reset() is used. This implementation skips - * count number of bytes in the target stream and increments - * the lineNumber count as bytes are skipped. + * Skips {@code count} number of bytes in this stream. Subsequent + * {@code read()}'s will not return these bytes unless {@code reset()} is + * used. This implementation skips {@code count} number of bytes in the + * filtered stream and increments the line number count whenever line + * terminator sequences are skipped. * * @param count * the number of bytes to skip. * @return the number of bytes actually skipped. - * * @throws IOException - * If the stream is already closed or another IOException - * occurs. + * if this stream is closed or another IOException occurs. + * @see #mark(int) + * @see #read() + * @see #reset() */ @Override public long skip(long count) throws IOException {