Add org.apache.commons.io.output.ProxyOutputStream.writeRepeat(*, long)

Author: garydgregory

src/changes/changes.xml

@@ -53,6 +53,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add"                due-to="strangelookingnerd, Gary Gregory">FileUtils#byteCountToDisplaySize() supports Zettabyte, Yottabyte, Ronnabyte and Quettabyte #763.</action>
       <action dev="ggregory" type="add"                due-to="strangelookingnerd, Gary Gregory">Add org.apache.commons.io.FileUtils.ONE_RB #763.</action>
       <action dev="ggregory" type="add"                due-to="strangelookingnerd, Gary Gregory">Add org.apache.commons.io.FileUtils.ONE_QB #763.</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add org.apache.commons.io.output.ProxyOutputStream.writeRepeat(byte[], int, int, long).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add org.apache.commons.io.output.ProxyOutputStream.writeRepeat(byte[], long).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add org.apache.commons.io.output.ProxyOutputStream.writeRepeat(int, long).</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory"             due-to="Gary Gregory">Bump commons-codec:commons-codec from 1.18.0 to 1.19.0.</action>
   </release>

src/main/java/org/apache/commons/io/output/ProxyOutputStream.java

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.io.output;
 
 import java.io.FilterOutputStream;
@@ -24,13 +25,10 @@
 import org.apache.commons.io.build.AbstractStreamBuilder;
 
 /**
- * A Proxy stream which acts as expected, that is it passes the method
- * 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.
+ * A Proxy stream which acts as expected, that is it passes the method 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.
+ * See the protected methods for ways in which a subclass can easily decorate a stream with custom pre-, post- or error processing functionality.
  * </p>
  */
 public class ProxyOutputStream extends FilterOutputStream {
@@ -72,7 +70,6 @@ public Builder() {
         public ProxyOutputStream get() throws IOException {
             return new ProxyOutputStream(this);
         }
-
     }
 
     @SuppressWarnings("resource") // caller closes
@@ -84,22 +81,19 @@ public ProxyOutputStream get() throws IOException {
     /**
      * Constructs a new ProxyOutputStream.
      *
-     * @param delegate  the OutputStream to delegate to.
+     * @param delegate the OutputStream to delegate to.
      */
     public ProxyOutputStream(final OutputStream delegate) {
         // the delegate is stored in a protected superclass variable named 'out'
         super(delegate);
     }
 
     /**
-     * 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.
+     * 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.
+     * Subclasses can override this method to add common post-processing functionality without having to override all the write methods. The default
+     * implementation does nothing.
      * </p>
      *
      * @param n number of bytes written.
@@ -112,13 +106,11 @@ protected void afterWrite(final int n) 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.
+     * 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.
+     * Subclasses can override this method to add common pre-processing functionality without having to override all the write methods. The default
+     * implementation does nothing.
      * </p>
      *
      * @param n number of bytes to be written.
@@ -157,8 +149,7 @@ public void flush() throws IOException {
     /**
      * Handle any IOExceptions thrown.
      * <p>
-     * This method provides a point to implement custom exception.
-     * handling. The default behavior is to re-throw the exception.
+     * This method provides a point to implement custom exception. handling. The default behavior is to re-throw the exception.
      * </p>
      *
      * @param e The IOException thrown.
@@ -214,7 +205,7 @@ public void write(final byte[] b) throws IOException {
     /**
      * Invokes the delegate's {@code write(byte[])} method.
      *
-     * @param b the bytes to write.
+     * @param b   the bytes to write.
      * @param off The start offset.
      * @param len The number of bytes to write.
      * @throws IOException if an I/O error occurs.
@@ -247,4 +238,50 @@ public void write(final int b) throws IOException {
         }
     }
 
+    /**
+     * Invokes the delegate's {@code write(byte[])} method for the {@code repeat} count.
+     *
+     * @param b      the bytes to write.
+     * @param off    The start offset.
+     * @param len    The number of bytes to write.
+     * @param repeat How many times to write the bytes in {@code b}.
+     * @throws IOException if an I/O error occurs.
+     * @since 2.21.0
+     */
+    public void writeRepeat(final byte[] b, final int off, final int len, final long repeat) throws IOException {
+        long remains = repeat;
+        while (remains-- > 0) {
+            write(b, off, len);
+        }
+    }
+
+    /**
+     * Invokes the delegate's {@code write(byte[])} method for the {@code repeat} count.
+     *
+     * @param b      the bytes to write.
+     * @param repeat How many times to write the bytes in {@code b}.
+     * @throws IOException if an I/O error occurs.
+     * @since 2.21.0
+     */
+    public void writeRepeat(final byte[] b, final long repeat) throws IOException {
+        long remains = repeat;
+        while (remains-- > 0) {
+            write(b);
+        }
+    }
+
+    /**
+     * Invokes the delegate's {@code write(int)} method.
+     *
+     * @param b      the byte to write.
+     * @param repeat How many times to write the byte in {@code b}.
+     * @throws IOException if an I/O error occurs.
+     * @since 2.21.0
+     */
+    public void writeRepeat(final int b, final long repeat) throws IOException {
+        long remains = repeat;
+        while (remains-- > 0) {
+            write(b);
+        }
+    }
 }

src/test/java/org/apache/commons/io/output/ProxyOutputStreamTest.java

@@ -34,7 +34,7 @@
  */
 class ProxyOutputStreamTest {
 
-    private ByteArrayOutputStream original;
+    private ByteArrayOutputStream target;
 
     private ProxyOutputStream proxied;
 
@@ -44,7 +44,7 @@ class ProxyOutputStreamTest {
 
     @BeforeEach
     public void setUp() {
-        original = new ByteArrayOutputStream() {
+        target = new ByteArrayOutputStream() {
 
             @Override
             public void write(final byte[] ba) {
@@ -64,12 +64,12 @@ public synchronized void write(final int ba) {
                 super.write(ba);
             }
         };
-        proxied = new ProxyOutputStream(original);
+        proxied = new ProxyOutputStream(target);
     }
 
     @Test
     void testBuilder() throws Exception {
-        assertSame(original, new ProxyOutputStream.Builder().setOutputStream(original).get().unwrap());
+        assertSame(target, new ProxyOutputStream.Builder().setOutputStream(target).get().unwrap());
     }
 
     @SuppressWarnings("resource")
@@ -79,42 +79,126 @@ void testSetReference() throws Exception {
         proxied.setReference(new ByteArrayOutputStream());
         proxied.write('y');
         assertFalse(hitByteArray.get());
-        assertEquals(0, original.size());
-        assertArrayEquals(ArrayUtils.EMPTY_BYTE_ARRAY, original.toByteArray());
+        assertEquals(0, target.size());
+        assertArrayEquals(ArrayUtils.EMPTY_BYTE_ARRAY, target.toByteArray());
     }
 
     @Test
     void testWriteByteArray() throws Exception {
         assertFalse(hitByteArray.get());
         proxied.write(new byte[] { 'y', 'z' });
         assertTrue(hitByteArray.get());
-        assertEquals(2, original.size());
-        assertArrayEquals(new byte[] { 'y', 'z' }, original.toByteArray());
+        assertEquals(2, target.size());
+        assertArrayEquals(new byte[] { 'y', 'z' }, target.toByteArray());
     }
 
     @Test
     void testWriteByteArrayAt() throws Exception {
         assertFalse(hitByteArrayAt.get());
         proxied.write(new byte[] { 'y', 'z' }, 1, 1);
         assertTrue(hitByteArrayAt.get());
-        assertEquals(1, original.size());
-        assertArrayEquals(new byte[] { 'z' }, original.toByteArray());
+        assertEquals(1, target.size());
+        assertArrayEquals(new byte[] { 'z' }, target.toByteArray());
+    }
+
+    @Test
+    void testWriteByteArrayAtRepeat() throws Exception {
+        // repeat -1
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, 1, 1, 0);
+        assertFalse(hitByteArrayAt.get());
+        hitByteArray.set(false);
+        assertEquals(0, target.size());
+        assertArrayEquals(new byte[] {}, target.toByteArray());
+        // repeat 0
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, 1, 1, 0);
+        assertFalse(hitByteArrayAt.get());
+        hitByteArray.set(false);
+        assertEquals(0, target.size());
+        assertArrayEquals(new byte[] {}, target.toByteArray());
+        // repeat 1
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, 1, 1, 1);
+        assertTrue(hitByteArrayAt.get());
+        hitByteArray.set(false);
+        assertEquals(1, target.size());
+        assertArrayEquals(new byte[] { 'z' }, target.toByteArray());
+        // repeat 2
+        proxied.writeRepeat(new byte[] { 'y', 'x' }, 1, 1, 2);
+        assertTrue(hitByteArrayAt.get());
+        assertEquals(3, target.size());
+        assertArrayEquals(new byte[] { 'z', 'x', 'x' }, target.toByteArray());
+    }
+
+    @Test
+    void testWriteByteArrayRepeat() throws Exception {
+        // repeat -1
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, -1);
+        assertFalse(hitByteArray.get());
+        hitByteArray.set(false);
+        assertEquals(0, target.size());
+        assertArrayEquals(new byte[] {}, target.toByteArray());
+        // repeat 0
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, 0);
+        assertFalse(hitByteArray.get());
+        hitByteArray.set(false);
+        assertEquals(0, target.size());
+        assertArrayEquals(new byte[] {}, target.toByteArray());
+        // repeat 1
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, 1);
+        assertTrue(hitByteArray.get());
+        hitByteArray.set(false);
+        assertEquals(2, target.size());
+        assertArrayEquals(new byte[] { 'y', 'z' }, target.toByteArray());
+        // repeat 2
+        proxied.writeRepeat(new byte[] { 'y', 'z' }, 2);
+        assertTrue(hitByteArray.get());
+        assertEquals(6, target.size());
+        assertArrayEquals(new byte[] { 'y', 'z', 'y', 'z' , 'y', 'z' }, target.toByteArray());
     }
 
     @Test
     void testWriteInt() throws Exception {
         assertFalse(hitInt.get());
         proxied.write('y');
         assertTrue(hitInt.get());
-        assertEquals(1, original.size());
-        assertEquals('y', original.toByteArray()[0]);
+        assertEquals(1, target.size());
+        assertEquals('y', target.toByteArray()[0]);
+    }
+
+    @Test
+    void testWriteIntRepeat() throws Exception {
+        // repeat -1
+        assertFalse(hitInt.get());
+        proxied.writeRepeat('y', -1);
+        assertFalse(hitInt.get());
+        assertEquals(0, target.size());
+        assertArrayEquals(new byte[] {}, target.toByteArray());
+        // repeat 0
+        assertFalse(hitInt.get());
+        proxied.writeRepeat('y', 0);
+        assertFalse(hitInt.get());
+        assertEquals(0, target.size());
+        assertArrayEquals(new byte[] {}, target.toByteArray());
+        // repeat 1
+        assertFalse(hitInt.get());
+        proxied.writeRepeat('y', 1);
+        assertTrue(hitInt.get());
+        hitInt.set(false);
+        assertEquals(1, target.size());
+        assertArrayEquals(new byte[] { 'y' }, target.toByteArray());
+        // repeat 2
+        assertFalse(hitInt.get());
+        proxied.writeRepeat('z', 2);
+        assertTrue(hitInt.get());
+        hitInt.set(false);
+        assertEquals(3, target.size());
+        assertArrayEquals(new byte[] { 'y', 'z', 'z' }, target.toByteArray());
     }
 
     @Test
     void testWriteNullArrayProxiesToUnderlying() throws Exception {
         assertFalse(hitByteArray.get());
         final byte[] ba = null;
-        assertThrows(NullPointerException.class, () -> original.write(ba));
+        assertThrows(NullPointerException.class, () -> target.write(ba));
         assertTrue(hitByteArray.get());
         assertThrows(NullPointerException.class, () -> proxied.write(ba));
         assertTrue(hitByteArray.get());