Add ProxyOutputStream.Builder

Author: garydgregory

src/changes/changes.xml

@@ -61,6 +61,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add ProxyInputStream.setReference(InputStream), was package-private setIn(InputStream).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add ProxyOutputStream.setReference(OutputStream).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add RandomAccessFileInputStream.copy(long, long, OutputStream).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add ProxyOutputStream.Builder.</action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update"             due-to="Dependabot, Gary Gregory">Bump commons.bytebuddy.version from 1.15.10 to 1.16.1 #710, #715.</action>
       <action dev="ggregory" type="update"             due-to="Gary Gregory">Bump commons-codec:commons-codec from 1.17.1 to 1.17.2.</action>

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

@@ -21,6 +21,7 @@
 import java.io.OutputStream;
 
 import org.apache.commons.io.IOUtils;
+import org.apache.commons.io.build.AbstractStreamBuilder;
 
 /**
  * A Proxy stream which acts as expected, that is it passes the method
@@ -34,6 +35,46 @@
  */
 public class ProxyOutputStream extends FilterOutputStream {
 
+    /**
+     * Builds instances of {@link ProxyOutputStream}.
+     * <p>
+     * This class does not provide a convenience static {@code builder()} method so that subclasses can.
+     * </p> 
+     *
+     * @since 2.19.0
+     */
+    public static class Builder extends AbstractStreamBuilder<ProxyOutputStream, Builder> {
+
+        /**
+         * Constructs a new builder of {@link ProxyOutputStream}.
+         */
+        public Builder() {
+            // empty
+        }
+
+        /**
+         * Builds a new {@link ProxyOutputStream}.
+         * <p>
+         * This builder use the following aspects:
+         * </p>
+         * <ul>
+         * <li>{@link #getOutputStream()}</li>
+         * </ul>
+         *
+         * @return a new instance.
+         * @throws IllegalStateException         if the {@code origin} is {@code null}.
+         * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
+         * @throws IOException                   if an I/O error occurs.
+         * @see #getOutputStream()
+         */
+        @SuppressWarnings("resource") // Caller closes.
+        @Override
+        public ProxyOutputStream get() throws IOException {
+            return new ProxyOutputStream(getOutputStream());
+        }
+
+    }
+
     /**
      * Constructs a new ProxyOutputStream.
      *
@@ -128,6 +169,18 @@ public ProxyOutputStream setReference(final OutputStream out) {
         return this;
     }
 
+    /**
+     * Unwraps this instance by returning the underlying {@link OutputStream}.
+     * <p>
+     * Use with caution; useful to query the underlying {@link OutputStream}.
+     * </p>
+     *
+     * @return the underlying {@link OutputStream}.
+     */
+    OutputStream unwrap() {
+        return out;
+    }
+
     /**
      * Invokes the delegate's {@code write(byte[])} method.
      * @param bts the bytes to write

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

@@ -19,6 +19,7 @@
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -58,6 +59,11 @@ public synchronized void write(final int ba) {
         proxied = new ProxyOutputStream(original);
     }
 
+    @Test
+    public void testBuilder() throws Exception {
+        assertSame(original, new ProxyOutputStream.Builder().setOutputStream(original).get().unwrap());
+    }
+
     @SuppressWarnings("resource")
     @Test
     public void testSetReference() throws Exception {