Add ThresholdingOutputStream.getOutputStream() and deprecate getStream()

Author: garydgregory

src/changes/changes.xml

@@ -98,6 +98,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add PathMatcherFileFilter to adapt java.nio.file.PathMatcher.
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add ThresholdingOutputStream.getOutputStream() and deprecate getStream().
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Dependabot">
         Bump jimfs from 1.2 to 1.3.0 #465 (tests).

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

@@ -118,6 +118,7 @@ public void close() throws IOException {
         } catch (final IOException ignored) {
             // ignore
         }
+        // TODO for 4.0: Replace with getOutputStream()
         getStream().close();
     }
 
@@ -129,6 +130,7 @@ public void close() throws IOException {
     @SuppressWarnings("resource") // the underlying stream is managed by a subclass.
     @Override
     public void flush() throws IOException {
+        // TODO for 4.0: Replace with getOutputStream()
         getStream().flush();
     }
 
@@ -142,14 +144,27 @@ public long getByteCount() {
     }
 
     /**
-     * Returns the underlying output stream, to which the corresponding {@link OutputStream} methods in this class will
+     * Gets the underlying output stream, to which the corresponding {@link OutputStream} methods in this class will
      * ultimately delegate.
      *
      * @return The underlying output stream.
-     *
      * @throws IOException if an error occurs.
+     * @deprecated Use {@link #getOutputStream()}.
      */
+    @Deprecated
     protected OutputStream getStream() throws IOException {
+        return getOutputStream();
+    }
+
+    /**
+     * Gets the underlying output stream, to which the corresponding {@link OutputStream} methods in this class will
+     * ultimately delegate.
+     *
+     * @return The underlying output stream.
+     * @throws IOException if an error occurs.
+     * @since 2.14.0
+     */
+    protected OutputStream getOutputStream() throws IOException {
         return outputStreamGetter.apply(this);
     }
 
@@ -212,6 +227,7 @@ protected void thresholdReached() throws IOException {
     @Override
     public void write(final byte[] b) throws IOException {
         checkThreshold(b.length);
+        // TODO for 4.0: Replace with getOutputStream()
         getStream().write(b);
         written += b.length;
     }
@@ -229,6 +245,7 @@ public void write(final byte[] b) throws IOException {
     @Override
     public void write(final byte[] b, final int off, final int len) throws IOException {
         checkThreshold(len);
+        // TODO for 4.0: Replace with getOutputStream()
         getStream().write(b, off, len);
         written += len;
     }
@@ -244,6 +261,7 @@ public void write(final byte[] b, final int off, final int len) throws IOExcepti
     @Override
     public void write(final int b) throws IOException {
         checkThreshold(1);
+        // TODO for 4.0: Replace with getOutputStream()
         getStream().write(b);
         written++;
     }

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

@@ -33,7 +33,7 @@
 public class ThresholdingOutputStreamTest {
 
     @Test
-    public void testSetByteCount() throws Exception {
+    public void testSetByteCount_Stream() throws Exception {
         final AtomicBoolean reached = new AtomicBoolean(false);
         try (ThresholdingOutputStream tos = new ThresholdingOutputStream(3) {
             {
@@ -57,6 +57,31 @@ protected void thresholdReached() throws IOException {
         }
     }
 
+    @Test
+    public void testSetByteCount_OutputStream() throws Exception {
+        final AtomicBoolean reached = new AtomicBoolean(false);
+        try (ThresholdingOutputStream tos = new ThresholdingOutputStream(3) {
+            {
+                setByteCount(2);
+            }
+
+            @Override
+            protected OutputStream getOutputStream() throws IOException {
+                return new ByteArrayOutputStream(4);
+            }
+
+            @Override
+            protected void thresholdReached() throws IOException {
+                reached.set(true);
+            }
+        }) {
+            tos.write('a');
+            assertFalse(reached.get());
+            tos.write('a');
+            assertTrue(reached.get());
+        }
+    }
+
     @Test
     public void testThresholdIOConsumer() throws Exception {
         final AtomicBoolean reached = new AtomicBoolean();