Add NullOutputStream.INSTANCE and deprecate NULL_OUTPUT_STREAM.

Author: Gary Gregory

src/changes/changes.xml

@@ -87,6 +87,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add ClosedWriter.INSTANCE and deprecate CLOSED_WRITER.
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add NullOutputStream.INSTANCE and deprecate NULL_OUTPUT_STREAM.
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Dependabot">
         Bump Maven Javadoc plugin from 3.2.0 to 3.3.0.

src/main/java/org/apache/commons/io/IOUtils.java

@@ -772,7 +772,7 @@ public static void closeQuietly(final Writer writer) {
      */
     public static long consume(final InputStream input)
             throws IOException {
-        return copyLarge(input, NullOutputStream.NULL_OUTPUT_STREAM, getByteArray());
+        return copyLarge(input, NullOutputStream.INSTANCE, getByteArray());
     }
 
     /**

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

@@ -39,9 +39,19 @@ public NullOutputStream() {
     }
 
     /**
-     * The singleton.
+     * The singleton instance.
+     *
+     * @since 2.12.0
+     */
+    public static final NullOutputStream INSTANCE = new NullOutputStream();
+
+    /**
+     * The singleton instance.
+     *
+     * @deprecated Use {@link #INSTANCE}.
      */
-    public static final NullOutputStream NULL_OUTPUT_STREAM = new NullOutputStream();
+    @Deprecated
+    public static final NullOutputStream NULL_OUTPUT_STREAM = INSTANCE;
 
     /**
      * Does nothing - output to {@code /dev/null}.

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

@@ -39,7 +39,7 @@ public class NullPrintStream extends PrintStream {
      */
     public NullPrintStream() {
         // Relies on the default charset which is OK since we are not actually writing.
-        super(NullOutputStream.NULL_OUTPUT_STREAM);
+        super(NullOutputStream.INSTANCE);
     }
 
 }

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

@@ -40,7 +40,7 @@ public class ThresholdingOutputStream extends OutputStream {
     /**
      * Noop output stream getter function.
      */
-    private static final IOFunction<ThresholdingOutputStream, OutputStream> NOOP_OS_GETTER = os -> NullOutputStream.NULL_OUTPUT_STREAM;
+    private static final IOFunction<ThresholdingOutputStream, OutputStream> NOOP_OS_GETTER = os -> NullOutputStream.INSTANCE;
 
     /**
      * The threshold at which the event will be triggered.

src/test/java/org/apache/commons/io/IOUtilsCopyTestCase.java

@@ -87,7 +87,7 @@ public void testCopy_inputStreamToOutputStream() throws Exception {
     public void testCopy_inputStreamToOutputStream_IO84() throws Exception {
         final long size = (long)Integer.MAX_VALUE + (long)1;
         final InputStream  in  = new NullInputStream(size);
-        final OutputStream out = NullOutputStream.NULL_OUTPUT_STREAM;
+        final OutputStream out = NullOutputStream.INSTANCE;
 
         // Test copy() method
         assertEquals(-1, IOUtils.copy(in, out));

src/test/java/org/apache/commons/io/IOUtilsTestCase.java

@@ -500,7 +500,7 @@ public void testConstants() {
     public void testConsume() throws Exception {
         final long size = (long) Integer.MAX_VALUE + (long) 1;
         final InputStream in = new NullInputStream(size);
-        final OutputStream out = NullOutputStream.NULL_OUTPUT_STREAM;
+        final OutputStream out = NullOutputStream.INSTANCE;
 
         // Test copy() method
         assertEquals(-1, IOUtils.copy(in, out));

src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java

@@ -283,7 +283,7 @@ private void testNotificationCallbacks(final int bufferSize) throws IOException
         try (final ObservableInputStream ois = new ObservableInputStream(new ByteArrayInputStream(buffer),
             lengthObserver, methodCountObserver)) {
             assertEquals(IOUtils.DEFAULT_BUFFER_SIZE,
-                IOUtils.copy(ois, NullOutputStream.NULL_OUTPUT_STREAM, bufferSize));
+                IOUtils.copy(ois, NullOutputStream.INSTANCE, bufferSize));
         }
         assertEquals(IOUtils.DEFAULT_BUFFER_SIZE, lengthObserver.getTotal());
         assertEquals(1, methodCountObserver.getClosedCount());

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

@@ -76,7 +76,7 @@ public void testLargeFiles_IO84() throws Exception {
         final long size = (long) Integer.MAX_VALUE + (long) 1;
 
         final NullInputStream mock = new NullInputStream(size);
-        final CountingOutputStream cos = new CountingOutputStream(NullOutputStream.NULL_OUTPUT_STREAM);
+        final CountingOutputStream cos = new CountingOutputStream(NullOutputStream.INSTANCE);
 
         // Test integer methods
         IOUtils.copyLarge(mock, cos);

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

@@ -40,14 +40,14 @@ private void process(final NullOutputStream nos) throws IOException {
 
     @Test
     public void testNewInstance() throws IOException {
-        try (final NullOutputStream nos = NullOutputStream.NULL_OUTPUT_STREAM) {
+        try (final NullOutputStream nos = NullOutputStream.INSTANCE) {
             process(nos);
         }
     }
 
     @Test
     public void testSingleton() throws IOException {
-        try (final NullOutputStream nos = NullOutputStream.NULL_OUTPUT_STREAM) {
+        try (final NullOutputStream nos = NullOutputStream.INSTANCE) {
             process(nos);
         }
     }