Replace CloseShield* constructors with factory methods (#173)

* Replace CloseShield* constructors with factory methods

* Renamed CloseShield*.dontClose to wrap

* Changed parameter names and tags as requested

Author: robtimus

src/main/java/org/apache/commons/io/input/CloseShieldInputStream.java

@@ -35,7 +35,11 @@ public class CloseShieldInputStream extends ProxyInputStream {
      * closed.
      *
      * @param in underlying input stream
+     * @deprecated Using this constructor prevents IDEs from warning if
+     *             the underlying input stream is never closed.
+     *             Use {@link #wrap(InputStream)} instead.
      */
+    @Deprecated
     public CloseShieldInputStream(final InputStream in) {
         super(in);
     }
@@ -50,4 +54,16 @@ public void close() {
         in = ClosedInputStream.CLOSED_INPUT_STREAM;
     }
 
+    /**
+     * Creates a proxy that shields the given input stream from being
+     * closed.
+     *
+     * @param inputStream the input stream to wrap
+     * @return the created proxy
+     * @since 2.9.0
+     */
+    public static CloseShieldInputStream wrap(final InputStream inputStream) {
+        return new CloseShieldInputStream(inputStream);
+    }
+
 }

src/main/java/org/apache/commons/io/input/CloseShieldReader.java

@@ -35,7 +35,11 @@ public class CloseShieldReader extends ProxyReader {
      * closed.
      *
      * @param in underlying reader
+     * @deprecated Using this constructor prevents IDEs from warning if
+     *             the underlying reader is never closed.
+     *             Use {@link #wrap(Reader)} instead.
      */
+    @Deprecated
     public CloseShieldReader(final Reader in) {
         super(in);
     }
@@ -50,4 +54,16 @@ public void close() {
         in = ClosedReader.CLOSED_READER;
     }
 
+    /**
+     * Creates a proxy that shields the given reader from being
+     * closed.
+     *
+     * @param reader the reader to wrap
+     * @return the created proxy
+     * @since 2.9.0
+     */
+    public static CloseShieldReader wrap(final Reader reader) {
+        return new CloseShieldReader(reader);
+    }
+
 }

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

@@ -35,7 +35,11 @@ public class CloseShieldOutputStream extends ProxyOutputStream {
      * closed.
      *
      * @param out underlying output stream
+     * @deprecated Using this constructor prevents IDEs from warning if
+     *             the underlying output stream is never closed.
+     *             Use {@link #wrap(OutputStream)} instead.
      */
+    @Deprecated
     public CloseShieldOutputStream(final OutputStream out) {
         super(out);
     }
@@ -50,4 +54,16 @@ public void close() {
         out = ClosedOutputStream.CLOSED_OUTPUT_STREAM;
     }
 
+    /**
+     * Creates a proxy that shields the given output stream from being
+     * closed.
+     *
+     * @param outputStream the output stream to wrap
+     * @return the created proxy
+     * @since 2.9.0
+     */
+    public static CloseShieldOutputStream wrap(final OutputStream outputStream) {
+        return new CloseShieldOutputStream(outputStream);
+    }
+
 }

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

@@ -33,7 +33,11 @@ public class CloseShieldWriter extends ProxyWriter {
      * Creates a proxy that shields the given writer from being closed.
      *
      * @param out underlying writer
+     * @deprecated Using this constructor prevents IDEs from warning if
+     *             the underlying writer is never closed.
+     *             Use {@link #wrap(Writer)} instead.
      */
+    @Deprecated
     public CloseShieldWriter(final Writer out) {
         super(out);
     }
@@ -47,4 +51,15 @@ public void close() {
         out = ClosedWriter.CLOSED_WRITER;
     }
 
+    /**
+     * Creates a proxy that shields the given writer from being closed.
+     *
+     * @param writer the writer to wrap
+     * @return the created proxy
+     * @since 2.9.0
+     */
+    public static CloseShieldWriter wrap(final Writer writer) {
+        return new CloseShieldWriter(writer);
+    }
+
 }

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

@@ -48,7 +48,7 @@ public void close() {
                 closed = true;
             }
         };
-        shielded = new CloseShieldInputStream(original);
+        shielded = CloseShieldInputStream.wrap(original);
         closed = false;
     }
 

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

@@ -42,7 +42,7 @@ public class CloseShieldReaderTest {
     public void setUp() {
         data = "xyz";
         original = spy(new CharSequenceReader(data));
-        shielded = new CloseShieldReader(original);
+        shielded = CloseShieldReader.wrap(original);
     }
 
     @Test

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

@@ -18,7 +18,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.fail;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.io.IOException;
 import java.io.OutputStream;
@@ -45,20 +45,15 @@ public void close() {
                 closed = true;
             }
         };
-        shielded = new CloseShieldOutputStream(original);
+        shielded = CloseShieldOutputStream.wrap(original);
         closed = false;
     }
 
     @Test
     public void testClose() throws IOException {
         shielded.close();
         assertFalse(closed, "closed");
-        try {
-            shielded.write('x');
-            fail("write(b)");
-        } catch (final IOException ignore) {
-            // expected
-        }
+        assertThrows(IOException.class, () -> shielded.write('x'), "write(b)");
         original.write('y');
         assertEquals(1, original.size());
         assertEquals('y', original.toByteArray()[0]);

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

@@ -17,7 +17,7 @@
 package org.apache.commons.io.output;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.fail;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.spy;
 import static org.mockito.Mockito.verify;
@@ -40,19 +40,14 @@ public class CloseShieldWriterTest {
     @BeforeEach
     public void setUp() {
         original = spy(new StringBuilderWriter());
-        shielded = new CloseShieldWriter(original);
+        shielded = CloseShieldWriter.wrap(original);
     }
 
     @Test
     public void testClose() throws IOException {
         shielded.close();
         verify(original, never()).close();
-        try {
-            shielded.write('x');
-            fail("write(c)");
-        } catch (final IOException ignore) {
-            // expected
-        }
+        assertThrows(IOException.class, () -> shielded.write('x'), "write(c)");
         original.write('y');
         assertEquals(1, original.getBuilder().length());
         assertEquals('y', original.toString().charAt(0));