You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2006/10/11 16:05:05 UTC
svn commit: r462807 - in
/jakarta/commons/proper/io/trunk/src/java/org/apache/commons/io:
input/CountingInputStream.java output/CountingOutputStream.java
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:bayard@apache.org">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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org