Add tests

- Remove unused exception from signature of
CloseShieldChannelHandler.invokeObjectMethod(Object, Method, Object[])
- Test AsynchronousChannel
- Test AsynchronousByteChannel
- Test NetworkChannel
- Test MulticastChannel
- Test InterruptibleChannel
- Add @SuppressWarnings value
- Inline single use local variable
- Javadoc
- Sort members
- Use final

Author: garydgregory

src/changes/changes.xml

@@ -66,7 +66,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="pkarwasz" type="add"                due-to="Piotr P. Karwasz">Add org.apache.commons.io.file.PathUtils.getPath(String, String).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add org.apache.commons.io.channels.ByteArraySeekableByteChannel.</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add IOIterable.asIterable().</action>
-      <action dev="pkarwasz" type="add"                due-to="Piotr P. Karwasz">Add Channels.closeShield(Channel) for close-shielded NIO Channel proxies.</action>
+      <action dev="pkarwasz" type="add"                due-to="Piotr P. Karwasz">Add CloseShieldChannel to close-shielded NIO Channels.</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory"             due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 85 to 88 #774, #783.</action>
       <action type="update" dev="ggregory"             due-to="Gary Gregory">[test] Bump commons-codec:commons-codec from 1.18.0 to 1.19.0.</action>

src/main/java/org/apache/commons/io/channels/CloseShieldChannel.java

@@ -14,26 +14,42 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.io.channels;
 
-import java.lang.reflect.InvocationHandler;
+import java.io.Closeable;
 import java.lang.reflect.Proxy;
 import java.nio.channels.Channel;
 import java.util.LinkedHashSet;
 import java.util.Objects;
 import java.util.Set;
 
 /**
- * Utility to create a close-shielding proxy for a {@link Channel}.
+ * Creates a close-shielding proxy for a {@link Channel}.
  *
- * <p>The returned proxy will implement all {@link Channel} sub-interfaces that the delegate implements.</p>
+ * <p>
+ * The returned proxy will implement all {@link Channel} sub-interfaces that the delegate implements.
+ * </p>
  *
+ * @see Channel
+ * @see Closeable
  * @since 2.21.0
  */
 public final class CloseShieldChannel {
 
-    private CloseShieldChannel() {
-        // no instance
+    private static Class<?>[] collectChannelInterfaces(final Class<?> type) {
+        final Set<Class<?>> out = new LinkedHashSet<>();
+        collectChannelInterfaces(type, out);
+        return out.toArray(new Class<?>[0]);
+    }
+
+    private static void collectChannelInterfaces(final Class<?> type, final Set<Class<?>> out) {
+        // Visit interfaces
+        for (final Class<?> iface : type.getInterfaces()) {
+            if (Channel.class.isAssignableFrom(iface) && out.add(iface)) {
+                collectChannelInterfaces(iface, out);
+            }
+        }
     }
 
     /**
@@ -43,42 +59,25 @@ private CloseShieldChannel() {
      * @param <T>     Any Channel type (interface or class).
      * @return A proxy that shields {@code close()} and enforces closed semantics on other calls.
      */
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings({ "unchecked", "resource" }) // caller closes
     public static <T extends Channel> T wrap(final T channel) {
         Objects.requireNonNull(channel, "channel");
-
         // Fast path: already our shield
         if (Proxy.isProxyClass(channel.getClass())) {
-            final InvocationHandler handler = Proxy.getInvocationHandler(channel);
-            if (handler instanceof CloseShieldChannelHandler) {
+            if (Proxy.getInvocationHandler(channel) instanceof CloseShieldChannelHandler) {
                 return channel;
             }
         }
-
         // Collect only Channel sub-interfaces.
         Class<?>[] ifaces = collectChannelInterfaces(channel.getClass());
         if (ifaces.length == 0) {
-            ifaces = new Class<?>[] {Channel.class}; // fallback to minimal surface
+            ifaces = new Class<?>[] { Channel.class }; // fallback to root surface
         }
-
-        return (T) Proxy.newProxyInstance(
-                channel.getClass().getClassLoader(), // use delegate's loader
-                ifaces,
-                new CloseShieldChannelHandler(channel));
-    }
-
-    private static Class<?>[] collectChannelInterfaces(final Class<?> type) {
-        final Set<Class<?>> out = new LinkedHashSet<>();
-        collectChannelInterfaces(type, out);
-        return out.toArray(new Class<?>[0]);
+        return (T) Proxy.newProxyInstance(channel.getClass().getClassLoader(), // use delegate's loader
+                ifaces, new CloseShieldChannelHandler(channel));
     }
 
-    private static void collectChannelInterfaces(final Class<?> type, final Set<Class<?>> out) {
-        // Visit interfaces
-        for (Class<?> iface : type.getInterfaces()) {
-            if (Channel.class.isAssignableFrom(iface) && out.add(iface)) {
-                collectChannelInterfaces(iface, out);
-            }
-        }
+    private CloseShieldChannel() {
+        // no instance
     }
 }

src/main/java/org/apache/commons/io/channels/CloseShieldChannelHandler.java

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.io.channels;
 
 import java.lang.reflect.InvocationHandler;
@@ -28,6 +29,39 @@
 
 final class CloseShieldChannelHandler implements InvocationHandler {
 
+    /**
+     * Tests whether the given method is allowed to be called after the shield is closed.
+     *
+     * @param declaringClass The class declaring the method.
+     * @param name           The method name.
+     * @param parameterCount The number of parameters.
+     * @return {@code true} if the method is allowed after {@code close()}, {@code false} otherwise.
+     */
+    private static boolean isAllowedAfterClose(final Class<?> declaringClass, final String name, final int parameterCount) {
+        // JDK explicitly allows NetworkChannel.supportedOptions() post-close
+        return parameterCount == 0 && name.equals("supportedOptions") && NetworkChannel.class.equals(declaringClass);
+    }
+
+    /**
+     * Tests whether the given method returns 'this' (the channel) as per JDK spec.
+     *
+     * @param declaringClass The class declaring the method.
+     * @param name           The method name.
+     * @param parameterCount The number of parameters.
+     * @return {@code true} if the method returns 'this', {@code false} otherwise.
+     */
+    private static boolean returnsThis(final Class<?> declaringClass, final String name, final int parameterCount) {
+        if (SeekableByteChannel.class.equals(declaringClass)) {
+            // SeekableByteChannel.position(long) and truncate(long) return 'this'
+            return parameterCount == 1 && (name.equals("position") || name.equals("truncate"));
+        }
+        if (NetworkChannel.class.equals(declaringClass)) {
+            // NetworkChannel.bind and NetworkChannel.setOption returns 'this'
+            return parameterCount == 1 && name.equals("bind") || parameterCount == 2 && name.equals("setOption");
+        }
+        return false;
+    }
+
     private final Channel delegate;
     private volatile boolean closed;
 
@@ -40,96 +74,57 @@ public Object invoke(final Object proxy, final Method method, final Object[] arg
         final Class<?> declaringClass = method.getDeclaringClass();
         final String name = method.getName();
         final int parameterCount = method.getParameterCount();
-
         // 1) java.lang.Object methods
         if (declaringClass == Object.class) {
             return invokeObjectMethod(proxy, method, args);
         }
-
         // 2) Channel.close(): mark shield closed, do NOT close the delegate
         if (parameterCount == 0 && name.equals("close")) {
             closed = true;
             return null;
         }
-
         // 3) Channel.isOpen(): reflect shield state only
         if (parameterCount == 0 && name.equals("isOpen")) {
             return !closed && delegate.isOpen();
         }
-
         // 4) After the shield is closed, only allow a tiny allowlist of safe queries
         if (closed && !isAllowedAfterClose(declaringClass, name, parameterCount)) {
             throw new ClosedChannelException();
         }
-
         // 5) Delegate to the underlying channel and unwrap target exceptions
         try {
             final Object result = method.invoke(delegate, args);
             return returnsThis(declaringClass, name, parameterCount) ? proxy : result;
-        } catch (InvocationTargetException e) {
+        } catch (final InvocationTargetException e) {
             throw e.getCause();
         }
     }
 
-    /**
-     * Tests whether the given method is allowed to be called after the shield is closed.
-     *
-     * @param declaringClass The class declaring the method.
-     * @param name           The method name.
-     * @param parameterCount The number of parameters.
-     * @return {@code true} if the method is allowed after {@code close()}, {@code false} otherwise.
-     */
-    private static boolean isAllowedAfterClose(Class<?> declaringClass, String name, int parameterCount) {
-        // JDK explicitly allows NetworkChannel.supportedOptions() post-close
-        return parameterCount == 0 && name.equals("supportedOptions") && NetworkChannel.class.equals(declaringClass);
-    }
-
-    /**
-     * Tests whether the given method returns 'this' (the channel) as per JDK spec.
-     *
-     * @param declaringClass The class declaring the method.
-     * @param name           The method name.
-     * @param parameterCount The number of parameters.
-     * @return {@code true} if the method returns 'this', {@code false} otherwise.
-     */
-    private static boolean returnsThis(Class<?> declaringClass, String name, int parameterCount) {
-        if (SeekableByteChannel.class.equals(declaringClass)) {
-            // SeekableByteChannel.position(long) and truncate(long) return 'this'
-            return parameterCount == 1 && (name.equals("position") || name.equals("truncate"));
-        }
-        if (NetworkChannel.class.equals(declaringClass)) {
-            // NetworkChannel.bind and NetworkChannel.setOption returns 'this'
-            return parameterCount == 1 && name.equals("bind") || parameterCount == 2 && name.equals("setOption");
-        }
-        return false;
-    }
-
-    private Object invokeObjectMethod(final Object proxy, final Method method, final Object[] args)
-            throws ReflectiveOperationException {
+    private Object invokeObjectMethod(final Object proxy, final Method method, final Object[] args) {
         switch (method.getName()) {
-            case "toString":
-                return "CloseShield(" + delegate + ")";
-            case "hashCode":
-                return Objects.hashCode(delegate);
-            case "equals": {
-                final Object other = args[0];
-                if (other == null) {
-                    return false;
-                }
-                if (proxy == other) {
-                    return true;
-                }
-                if (Proxy.isProxyClass(other.getClass())) {
-                    final InvocationHandler h = Proxy.getInvocationHandler(other);
-                    if (h instanceof CloseShieldChannelHandler) {
-                        return Objects.equals(((CloseShieldChannelHandler) h).delegate, this.delegate);
-                    }
-                }
+        case "toString":
+            return "CloseShield(" + delegate + ")";
+        case "hashCode":
+            return Objects.hashCode(delegate);
+        case "equals": {
+            final Object other = args[0];
+            if (other == null) {
                 return false;
             }
-            default:
-                // Not possible, all non-final Object methods are handled above
-                return null;
+            if (proxy == other) {
+                return true;
+            }
+            if (Proxy.isProxyClass(other.getClass())) {
+                final InvocationHandler h = Proxy.getInvocationHandler(other);
+                if (h instanceof CloseShieldChannelHandler) {
+                    return Objects.equals(((CloseShieldChannelHandler) h).delegate, this.delegate);
+                }
+            }
+            return false;
+        }
+        default:
+            // Not possible, all non-final Object methods are handled above
+            return null;
         }
     }
 }