feat: Add Channels.closeShield for close-shield proxies of NIO channels (#786)

* feat: Add `Channels.closeShield` for close-shield proxies of NIO channels

Adds `Channels.closeShield(Channel)` to return a JDK proxy that preserves the delegate’s `Channel` sub-interfaces and shields the underlying channel from `close()`.

**Behavior**

* `close()` flips shield state; delegate is not closed.
* `isOpen()` reflects shield state.
* After shield-close, I/O/mutating methods throw `ClosedChannelException`; safe queries (e.g., `NetworkChannel.supportedOptions()`) still work.
* Fluent methods that return `this` (e.g., `SeekableByteChannel.position/truncate`, `NetworkChannel.bind/setOption`) return the **proxy**.
* Stable `equals`/`hashCode`/`toString`
* The method is idempotent (no double-wrapping).

**Tests**

* All methods of `SeekableByteChannel` / `NetworkChannel` and super-interfaces are tested.

* fix: rename to `CloseShieldChannel.wrap`

Author: ppkarwasz

src/changes/changes.xml

@@ -66,6 +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>
       <!-- 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

@@ -0,0 +1,84 @@
+/*
+ * 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
+ *
+ *      https://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.channels;
+
+import java.lang.reflect.InvocationHandler;
+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}.
+ *
+ * <p>The returned proxy will implement all {@link Channel} sub-interfaces that the delegate implements.</p>
+ *
+ * @since 2.21.0
+ */
+public final class CloseShieldChannel {
+
+    private CloseShieldChannel() {
+        // no instance
+    }
+
+    /**
+     * Wraps a channel to shield it from being closed.
+     *
+     * @param channel The underlying channel to shield, not {@code null}.
+     * @param <T>     Any Channel type (interface or class).
+     * @return A proxy that shields {@code close()} and enforces closed semantics on other calls.
+     */
+    @SuppressWarnings("unchecked")
+    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) {
+                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
+        }
+
+        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]);
+    }
+
+    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);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,135 @@
+/*
+ * 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
+ *
+ *      https://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.channels;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.nio.channels.Channel;
+import java.nio.channels.ClosedChannelException;
+import java.nio.channels.NetworkChannel;
+import java.nio.channels.SeekableByteChannel;
+import java.util.Objects;
+
+final class CloseShieldChannelHandler implements InvocationHandler {
+
+    private final Channel delegate;
+    private volatile boolean closed;
+
+    CloseShieldChannelHandler(final Channel delegate) {
+        this.delegate = Objects.requireNonNull(delegate, "delegate");
+    }
+
+    @Override
+    public Object invoke(final Object proxy, final Method method, final Object[] args) throws Throwable {
+        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) {
+            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 {
+        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);
+                    }
+                }
+                return false;
+            }
+            default:
+                // Not possible, all non-final Object methods are handled above
+                return null;
+        }
+    }
+}