IO-211: Pre- and post-processing support for proxied streams

jukka · jukka · commit 3ce24e5883f2 · 2009-08-17T21:37:30.000Z
Committed the proposed patch. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@805151 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/java/org/apache/commons/io/input/AutoCloseInputStream.java b/src/java/org/apache/commons/io/input/AutoCloseInputStream.java
@@ -65,58 +65,16 @@ public void close() throws IOException {
     }
 
     /**
-     * Reads and returns a single byte from the underlying input stream.
-     * If the underlying stream returns -1, the {@link #close()} method is
-     * called to automatically close and discard the stream.
+     * Automatically closes the stream if the end of stream was reached.
      *
-     * @return next byte in the stream, or -1 if no more bytes are available
-     * @throws IOException if the stream could not be read or closed
+     * @param n number of bytes read, or -1 if no more bytes are available
+     * @throws IOException if the stream could not be closed
      */
     @Override
-    public int read() throws IOException {
-        int n = in.read();
+    protected void afterRead(int n) throws IOException {
         if (n == -1) {
             close();
         }
-        return n;
-    }
-
-    /**
-     * Reads and returns bytes from the underlying input stream to the given
-     * buffer. If the underlying stream returns -1, the {@link #close()} method
-     * i called to automatically close and discard the stream.
-     *
-     * @param b buffer to which bytes from the stream are written
-     * @return number of bytes read, or -1 if no more bytes are available
-     * @throws IOException if the stream could not be read or closed
-     */
-    @Override
-    public int read(byte[] b) throws IOException {
-        int n = in.read(b);
-        if (n == -1) {
-            close();
-        }
-        return n;
-    }
-
-    /**
-     * Reads and returns bytes from the underlying input stream to the given
-     * buffer. If the underlying stream returns -1, the {@link #close()} method
-     * i called to automatically close and discard the stream.
-     *
-     * @param b buffer to which bytes from the stream are written
-     * @param off start offset within the buffer
-     * @param len maximum number of bytes to read
-     * @return number of bytes read, or -1 if no more bytes are available
-     * @throws IOException if the stream could not be read or closed
-     */
-    @Override
-    public int read(byte[] b, int off, int len) throws IOException {
-        int n = in.read(b, off, len);
-        if (n == -1) {
-            close();
-        }
-        return n;
     }
 
     /**
diff --git a/src/java/org/apache/commons/io/input/CountingInputStream.java b/src/java/org/apache/commons/io/input/CountingInputStream.java
@@ -44,54 +44,6 @@ public CountingInputStream(InputStream in) {
     }
 
     //-----------------------------------------------------------------------
-    /**
-     * 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[]) 
-     */
-    @Override
-    public int read(byte[] b) throws IOException {
-        int found = super.read(b);
-        this.count += (found >= 0) ? found : 0;
-        return found;
-    }
-
-    /**
-     * 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)
-     */
-    @Override
-    public int read(byte[] b, int off, int len) throws IOException {
-        int found = super.read(b, off, len);
-        this.count += (found >= 0) ? found : 0;
-        return found;
-    }
-
-    /**
-     * 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()
-     */
-    @Override
-    public int read() throws IOException {
-        int found = super.read();
-        this.count += (found >= 0) ? 1 : 0;
-        return found;
-    }
 
     /**
      * Skips the stream over the specified number of bytes, adding the skipped
@@ -109,6 +61,18 @@ public long skip(final long length) throws IOException {
         return skip;
     }
 
+    /**
+     * Adds the number of read bytes to the count.
+     *
+     * @param n number of bytes read, or -1 if no more bytes are available
+     */
+    @Override
+    protected void afterRead(int n) {
+        if (n != -1) {
+            this.count += n;
+        }
+    }
+
     //-----------------------------------------------------------------------
     /**
      * The number of bytes that have passed through this stream.
diff --git a/src/java/org/apache/commons/io/input/ProxyInputStream.java b/src/java/org/apache/commons/io/input/ProxyInputStream.java
@@ -28,6 +28,9 @@
  * It is an alternative base class to FilterInputStream
  * to increase reusability, because FilterInputStream changes the
  * methods being called, such as read(byte[]) to read(byte[], int, int).
+ * <p>
+ * See the protected methods for ways in which a subclass can easily decorate
+ * a stream with custom pre-, post- or error processing functionality.
  *
  * @author Stephen Colebourne
  * @version $Id$
@@ -52,7 +55,10 @@ public ProxyInputStream(InputStream proxy) {
     @Override
     public int read() throws IOException {
         try {
-            return in.read();
+            beforeRead(1);
+            int b = in.read();
+            afterRead(b != -1 ? 1 : -1);
+            return b;
         } catch (IOException e) {
             handleIOException(e);
             return -1;
@@ -68,7 +74,10 @@ public int read() throws IOException {
     @Override
     public int read(byte[] bts) throws IOException {
         try {
-            return in.read(bts);
+            beforeRead(bts.length);
+            int n = in.read(bts);
+            afterRead(n);
+            return n;
         } catch (IOException e) {
             handleIOException(e);
             return -1;
@@ -86,7 +95,10 @@ public int read(byte[] bts) throws IOException {
     @Override
     public int read(byte[] bts, int off, int len) throws IOException {
         try {
-            return in.read(bts, off, len);
+            beforeRead(len);
+            int n = in.read(bts, off, len);
+            afterRead(n);
+            return n;
         } catch (IOException e) {
             handleIOException(e);
             return -1;
@@ -168,6 +180,46 @@ public boolean markSupported() {
         return in.markSupported();
     }
 
+    /**
+     * Invoked by the read methods before the call is proxied. The number
+     * of bytes that the caller wanted to read (1 for the {@link #read()}
+     * method, buffer length for {@link #read(byte[])}, etc.) is given as
+     * an argument.
+     * <p>
+     * Subclasses can override this method to add common pre-processing
+     * functionality without having to override all the read methods.
+     * The default implementation does nothing.
+     * <p>
+     * Note this method is <em>not</em> called from {@link #skip(long)} or
+     * {@link #reset()}. You need to explicitly override those methods if
+     * you want to add pre-processing steps also to them.
+     *
+     * @since Commons IO 2.0
+     * @param n number of bytes that the caller asked to be read
+     * @throws IOException if the pre-processing fails
+     */
+    protected void beforeRead(int n) throws IOException {
+    }
+
+    /**
+     * Invoked by the read methods after the proxied call has returned
+     * successfully. The number of bytes returned to the caller (or -1 if
+     * the end of stream was reached) is given as an argument.
+     * <p>
+     * Subclasses can override this method to add common post-processing
+     * functionality without having to override all the read methods.
+     * The default implementation does nothing.
+     * <p>
+     * Note this method is <em>not</em> called from {@link #skip(long)} or
+     * {@link #reset()}. You need to explicitly override those methods if
+     * you want to add post-processing steps also to them.
+     *
+     * @since Commons IO 2.0
+     * @param n number of bytes read, or -1 if the end of stream was reached
+     * @throws IOException if the post-processing fails
+     */
+    protected void afterRead(int n) throws IOException {
+    }
 
     /**
      * Handle any IOExceptions thrown.
diff --git a/src/java/org/apache/commons/io/output/CountingOutputStream.java b/src/java/org/apache/commons/io/output/CountingOutputStream.java
@@ -43,48 +43,15 @@ public CountingOutputStream( OutputStream out ) {
     }
 
     //-----------------------------------------------------------------------
-    /**
-     * 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[])
-     */
-    @Override
-    public void write(byte[] b) throws IOException {
-        count += b.length;
-        super.write(b);
-    }
-
-    /**
-     * 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)
-     */
-    @Override
-    public void write(byte[] b, int off, int len) throws IOException {
-        count += len;
-        super.write(b, off, len);
-    }
 
     /**
-     * Writes a single byte to the output stream adding to the count of the
-     * number of bytes written.
+     * Updates the count with the number of bytes that are being written.
      *
-     * @param b  the byte to write
-     * @throws IOException if an I/O error occurs
-     * @see java.io.OutputStream#write(int)
+     * @param n number of bytes to be written to the stream
      */
     @Override
-    public void write(int b) throws IOException {
-        count++;
-        super.write(b);
+    protected void beforeWrite(int n) {
+        count += n;
     }
 
     //-----------------------------------------------------------------------
diff --git a/src/java/org/apache/commons/io/output/ProxyOutputStream.java b/src/java/org/apache/commons/io/output/ProxyOutputStream.java
@@ -25,6 +25,9 @@
  * calls on to the proxied stream and doesn't change which methods are 
  * being called. It is an alternative base class to FilterOutputStream
  * to increase reusability.
+ * <p>
+ * See the protected methods for ways in which a subclass can easily decorate
+ * a stream with custom pre-, post- or error processing functionality.
  * 
  * @author Stephen Colebourne
  * @version $Id$
@@ -49,7 +52,9 @@ public ProxyOutputStream(OutputStream proxy) {
     @Override
     public void write(int idx) throws IOException {
         try {
+            beforeWrite(1);
             out.write(idx);
+            afterWrite(1);
         } catch (IOException e) {
             handleIOException(e);
         }
@@ -63,7 +68,9 @@ public void write(int idx) throws IOException {
     @Override
     public void write(byte[] bts) throws IOException {
         try {
+            beforeWrite(bts.length);
             out.write(bts);
+            afterWrite(bts.length);
         } catch (IOException e) {
             handleIOException(e);
         }
@@ -79,7 +86,9 @@ public void write(byte[] bts) throws IOException {
     @Override
     public void write(byte[] bts, int st, int end) throws IOException {
         try {
+            beforeWrite(end);
             out.write(bts, st, end);
+            afterWrite(end);
         } catch (IOException e) {
             handleIOException(e);
         }
@@ -111,6 +120,39 @@ public void close() throws IOException {
         }
     }
 
+    /**
+     * Invoked by the write methods before the call is proxied. The number
+     * of bytes to be written (1 for the {@link #write(int)} method, buffer
+     * length for {@link #write(byte[])}, etc.) is given as an argument.
+     * <p>
+     * Subclasses can override this method to add common pre-processing
+     * functionality without having to override all the write methods.
+     * The default implementation does nothing.
+     *
+     * @since Commons IO 2.0
+     * @param n number of bytes to be written
+     * @throws IOException if the pre-processing fails
+     */
+    protected void beforeWrite(int n) throws IOException {
+    }
+
+    /**
+     * Invoked by the write methods after the proxied call has returned
+     * successfully. The number of bytes written (1 for the
+     * {@link #write(int)} method, buffer length for {@link #write(byte[])},
+     * etc.) is given as an argument.
+     * <p>
+     * Subclasses can override this method to add common post-processing
+     * functionality without having to override all the write methods.
+     * The default implementation does nothing.
+     *
+     * @since Commons IO 2.0
+     * @param n number of bytes written
+     * @throws IOException if the post-processing fails
+     */
+    protected void afterWrite(int n) throws IOException {
+    }
+
     /**
      * Handle any IOExceptions thrown.
      * <p>
