Author: scolebourne Date: Wed Oct 11 07:05:02 2006 New Revision: 462807 URL: http://svn.apache.org/viewvc?view=rev&rev=462807 Log: Javadoc, checkstyle and since tags
Modified: jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/input/CountingInputStream.java jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/output/CountingOutputStream.java Modified: jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/input/CountingInputStream.java URL: http://svn.apache.org/viewvc/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/input/CountingInputStream.java?view=diff&rev=462807&r1=462806&r2=462807 ============================================================================== --- jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/input/CountingInputStream.java (original) +++ jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/input/CountingInputStream.java Wed Oct 11 07:05:02 2006 @@ -20,8 +20,11 @@ import java.io.InputStream; /** - * A decorating input stream that counts the number of bytes that - * have passed through so far. + * A decorating input stream that counts the number of bytes that have passed + * through the stream so far. + * <p> + * A typical use case would be during debugging, to ensure that data is being + * read as expected. * * @author Henri Yandell * @author Marcelo Liberato @@ -34,15 +37,21 @@ /** * Constructs a new CountingInputStream. - * @param in InputStream to delegate to + * + * @param in the InputStream to delegate to */ public CountingInputStream(InputStream in) { super(in); } + //----------------------------------------------------------------------- /** - * Increases the count by super.read(b)'s return count - * + * Reads a number of bytes into the byte array, keeping count of the + * number read. + * + * @param b the buffer into which the data is read, not null + * @return the total number of bytes read into the buffer, -1 if end of stream + * @throws IOException if an I/O error occurs * @see java.io.InputStream#read(byte[]) */ public int read(byte[] b) throws IOException { @@ -52,8 +61,14 @@ } /** - * Increases the count by super.read(b, off, len)'s return count + * Reads a number of bytes into the byte array at a specific offset, + * keeping count of the number read. * + * @param b the buffer into which the data is read, not null + * @param off the start offset in the buffer + * @param len the maximum number of bytes to read + * @return the total number of bytes read into the buffer, -1 if end of stream + * @throws IOException if an I/O error occurs * @see java.io.InputStream#read(byte[], int, int) */ public int read(byte[] b, int off, int len) throws IOException { @@ -63,8 +78,11 @@ } /** - * Increases the count by 1 if a byte is successfully read. + * Reads the next byte of data adding to the count of bytes received + * if a byte is successfully read. * + * @return the byte read, -1 if end of stream + * @throws IOException if an I/O error occurs * @see java.io.InputStream#read() */ public int read() throws IOException { @@ -72,10 +90,14 @@ this.count += (found >= 0) ? 1 : 0; return found; } - + /** - * Increases the count by the number of skipped bytes. - * + * Skips the stream over the specified number of bytes, adding the skipped + * amount to the count. + * + * @param length the number of bytes to skip + * @return the actual number of bytes skipped + * @throws IOException if an I/O error occurs * @see java.io.InputStream#skip(long) */ public long skip(final long length) throws IOException { @@ -84,6 +106,7 @@ return skip; } + //----------------------------------------------------------------------- /** * The number of bytes that have passed through this stream. * <p> @@ -120,19 +143,21 @@ * result in incorrect count for files over 2GB. * * @return the number of bytes accumulated + * @since Commons IO 1.3 */ public long getByteCount() { return this.count; } /** - * Set the count back to 0. + * Set the byte count back to 0. * <p> * NOTE: This method is a replacement for <code>resetCount()</code> * and was added because that method returns an integer which will * result in incorrect count for files over 2GB. * - * @return the count previous to resetting. + * @return the count previous to resetting + * @since Commons IO 1.3 */ public synchronized long resetByteCount() { long tmp = this.count; Modified: jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/output/CountingOutputStream.java URL: http://svn.apache.org/viewvc/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/output/CountingOutputStream.java?view=diff&rev=462807&r1=462806&r2=462807 ============================================================================== --- jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/output/CountingOutputStream.java (original) +++ jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io/output/CountingOutputStream.java Wed Oct 11 07:05:02 2006 @@ -20,42 +20,71 @@ import java.io.OutputStream; /** - * Used in debugging, it counts the number of bytes that pass - * through it. + * A decorating output stream that counts the number of bytes that have passed + * through the stream so far. + * <p> + * A typical use case would be during debugging, to ensure that data is being + * written as expected. * - * @author <a href="mailto:[EMAIL PROTECTED]">Henri Yandell</a> + * @author Henri Yandell * @version $Id$ */ public class CountingOutputStream extends ProxyOutputStream { + /** The count of bytes that have passed. */ private long count; /** - * Constructs a CountingOutputStream. - * @param out the OutputStream to write to + * Constructs a new CountingOutputStream. + * + * @param out the OutputStream to write to */ public CountingOutputStream( OutputStream out ) { super(out); } - /** @see java.io.OutputStream#write(byte[]) */ + //----------------------------------------------------------------------- + /** + * Writes the contents of the specified byte array to this output stream + * keeping count of the number of bytes written. + * + * @param b the bytes to write, not null + * @throws IOException if an I/O error occurs + * @see java.io.OutputStream#write(byte[]) + */ public void write(byte[] b) throws IOException { count += b.length; super.write(b); } - /** @see java.io.OutputStream#write(byte[], int, int) */ + /** + * Writes a portion of the specified byte array to this output stream + * keeping count of the number of bytes written. + * + * @param b the bytes to write, not null + * @param off the start offset in the buffer + * @param len the maximum number of bytes to write + * @throws IOException if an I/O error occurs + * @see java.io.OutputStream#write(byte[], int, int) + */ public void write(byte[] b, int off, int len) throws IOException { count += len; super.write(b, off, len); } - /** @see java.io.OutputStream#write(int) */ + /** + * Writes a single byte to the output stream adding to the count of the + * number of bytes written. + * + * @param b the byte to write + * @see java.io.OutputStream#write(int) + */ public void write(int b) throws IOException { count++; super.write(b); } + //----------------------------------------------------------------------- /** * The number of bytes that have passed through this stream. * <p> @@ -67,7 +96,7 @@ * @deprecated use <code>getByteCount()</code> - see issue IO-84 */ public int getCount() { - return (int)getByteCount(); + return (int) getByteCount(); } /** @@ -81,36 +110,37 @@ * @deprecated use <code>resetByteCount()</code> - see issue IO-84 */ public synchronized int resetCount() { - return (int)resetByteCount(); + return (int) resetByteCount(); } /** * The number of bytes that have passed through this stream. * <p> - * <strong>N.B.</strong> This method was introduced as an - * alternative for the <code>getCount()</code> method - * because that method returns an integer which will result - * in incorrect count for files over 2GB being returned. + * NOTE: This method is a replacement for <code>getCount()</code>. + * It was added because that method returns an integer which will + * result in incorrect count for files over 2GB. * * @return the number of bytes accumulated + * @since Commons IO 1.3 */ public long getByteCount() { return this.count; } /** - * Set the count back to 0. + * Set the byte count back to 0. * <p> - * <strong>N.B.</strong> This method was introduced as an - * alternative for the <code>resetCount()</code> method - * because that method returns an integer which will result - * in incorrect count for files over 2GB being returned. + * NOTE: This method is a replacement for <code>resetCount()</code>. + * It was added because that method returns an integer which will + * result in incorrect count for files over 2GB. * - * @return the count previous to resetting. + * @return the count previous to resetting + * @since Commons IO 1.3 */ public synchronized long resetByteCount() { long tmp = this.count; this.count = 0; return tmp; } + } --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]