[IO-617] Add class CloseShieldWriter. #83.

- Applied partial patch from GitHub PR #83 from Rob Spoor which
contained duplication from another PR.
- Reformatted some files.
- Closes #83.

Author: Gary Gregory

src/changes/changes.xml

@@ -125,6 +125,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action issue="IO-616" dev="ggregory" type="add" due-to="Rob Spoor">
         Add class AppendableWriter. #87.
       </action>
+      <action issue="IO-617" dev="ggregory" type="add" due-to="Rob Spoor, Gary Gregory">
+        Add class CloseShieldWriter. #83.
+      </action>
     </release>
 
     <release version="2.6" date="2017-10-15" description="Java 7 required, Java 9 supported.">

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

@@ -47,7 +47,7 @@ public CloseShieldOutputStream(final OutputStream out) {
      */
     @Override
     public void close() {
-        out = new ClosedOutputStream();
+        out = ClosedOutputStream.CLOSED_OUTPUT_STREAM;
     }
 
 }

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

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.io.output;
+
+import java.io.Writer;
+
+/**
+ * Proxy stream that prevents the underlying writer from being closed.
+ * <p>
+ * This class is typically used in cases where a writer needs to be passed to a component that wants to explicitly close
+ * the writer even if other components would still use the writer for output.
+ * </p>
+ *
+ * @since 2.7
+ */
+public class CloseShieldWriter extends ProxyWriter {
+
+    /**
+     * Creates a proxy that shields the given writer from being closed.
+     *
+     * @param out underlying writer
+     */
+    public CloseShieldWriter(final Writer out) {
+        super(out);
+    }
+
+    /**
+     * Replaces the underlying writer with a {@link ClosedWriter} sentinel. The original writer will remain open, but
+     * this proxy will appear closed.
+     */
+    @Override
+    public void close() {
+        out = ClosedWriter.CLOSED_WRITER;
+    }
+
+}

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

@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.io.output;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.verify;
+
+import java.io.IOException;
+import java.io.Writer;
+
+import org.junit.Before;
+import org.junit.Test;
+
+/**
+ * JUnit Test Case for {@link CloseShieldWriter}.
+ */
+public class CloseShieldWriterTest {
+
+    private StringBuilderWriter original;
+
+    private Writer shielded;
+
+    @Before
+    public void setUp() {
+        original = spy(new StringBuilderWriter());
+        shielded = new CloseShieldWriter(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
+        }
+        original.write('y');
+        assertEquals(1, original.getBuilder().length());
+        assertEquals('y', original.toString().charAt(0));
+    }
+
+}

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

@@ -32,7 +32,7 @@ public class ClosedOutputStreamTest {
      * @throws Exception
      */
     @Test
-    public void testRead() throws Exception {
+    public void testWrite() throws Exception {
         try (ClosedOutputStream cos = new ClosedOutputStream()) {
             cos.write('x');
             fail("write(b)");