Fixes issues in CloseShieldChannel (#799)

* Fixes issues in `CloseShieldChannel`

Two bugs in the `CloseShieldChannel` helper make it unreliable in practice:

1. **Type-erasure bug in `T wrap(T)`**
   The method signature only works correctly when `T` is an **interface** extending `Channel`.
   Since Java’s type system doesn’t allow constraining `T` to “interface types only,” this could lead to unexpected runtime `ClassCastException`s even though the code compiles successfully.

2. **Incomplete interface discovery**
   The implementation only inspected interfaces **directly** implemented by the given channel’s class, ignoring those inherited from its superclasses.
   As a result, proxies for types such as `FileChannel` did not expose any of the interfaces declared on `FileChannel` itself.

#### Fixes

This PR addresses both issues:

* **Reworks the API signature**

  * Replaces `T wrap(T)` with its erasure: `Channel wrap(Channel)`.
  * Introduces a new overload: `T wrap(T, Class<T>)`, which allows callers to explicitly specify the interface type they expect.
    This version fails fast with a clear `IllegalArgumentException` if the provided type is not an interface, instead of allowing a `ClassCastException` later.

* **Improves interface collection logic**

  * Updates the implementation to include interfaces declared on superclasses, ensuring all relevant `Channel` interfaces are correctly proxied.

* Fixes interface discovery in `CloseShieldChannel`

This PR is split from #799.

The `CloseShieldChannel` implementation only inspects interfaces **directly** implemented by the given channel’s class, ignoring those inherited from its superclasses.
As a result, proxies for types such as `FileChannel` does not expose any of the interfaces declared on `FileChannel` itself.

* fix: add overloads for commons channel types

* fix: add `ByteChannel` overload to resolve ambiguity

* fix: Limit interfaces to those verified.

* fix: rollback previous test

* fix: Restore generic method

Author: ppkarwasz

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

@@ -19,17 +19,40 @@
 
 import java.io.Closeable;
 import java.lang.reflect.Proxy;
+import java.nio.channels.AsynchronousChannel;
+import java.nio.channels.ByteChannel;
 import java.nio.channels.Channel;
+import java.nio.channels.GatheringByteChannel;
+import java.nio.channels.InterruptibleChannel;
+import java.nio.channels.NetworkChannel;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.channels.ScatteringByteChannel;
+import java.nio.channels.SeekableByteChannel;
+import java.nio.channels.WritableByteChannel;
 import java.util.LinkedHashSet;
 import java.util.Objects;
 import java.util.Set;
 
 /**
  * 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 implements all {@link Channel} sub-interfaces that are both supported by this implementation and actually implemented by the given
+ * delegate.</p>
+ *
+ * <p>The following interfaces are supported:</p>
+ *
+ * <ul>
+ * <li>{@link AsynchronousChannel}</li>
+ * <li>{@link ByteChannel}</li>
+ * <li>{@link Channel}</li>
+ * <li>{@link GatheringByteChannel}</li>
+ * <li>{@link InterruptibleChannel}</li>
+ * <li>{@link NetworkChannel}</li>
+ * <li>{@link ReadableByteChannel}</li>
+ * <li>{@link ScatteringByteChannel}</li>
+ * <li>{@link SeekableByteChannel}</li>
+ * <li>{@link WritableByteChannel}</li>
+ * </ul>
  *
  * @see Channel
  * @see Closeable
@@ -44,7 +67,7 @@ private static Set<Class<?>> collectChannelInterfaces(final Class<?> type, final
         // Visit interfaces
         while (currentType != null) {
             for (final Class<?> iface : currentType.getInterfaces()) {
-                if (Channel.class.isAssignableFrom(iface) && out.add(iface)) {
+                if (CloseShieldChannelHandler.isSupported(iface) && out.add(iface)) {
                     collectChannelInterfaces(iface, out);
                 }
             }
@@ -57,8 +80,10 @@ private static Set<Class<?>> collectChannelInterfaces(final Class<?> type, final
      * 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).
+     * @param <T>     A supported channel type.
      * @return A proxy that shields {@code close()} and enforces closed semantics on other calls.
+     * @throws ClassCastException if {@code T} is not a supported channel type.
+     * @throws NullPointerException if {@code channel} is {@code null}.
      */
     @SuppressWarnings({ "unchecked", "resource" }) // caller closes
     public static <T extends Channel> T wrap(final T channel) {

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

@@ -21,14 +21,45 @@
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.lang.reflect.Proxy;
+import java.nio.channels.AsynchronousChannel;
+import java.nio.channels.ByteChannel;
 import java.nio.channels.Channel;
 import java.nio.channels.ClosedChannelException;
+import java.nio.channels.GatheringByteChannel;
+import java.nio.channels.InterruptibleChannel;
 import java.nio.channels.NetworkChannel;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.channels.ScatteringByteChannel;
 import java.nio.channels.SeekableByteChannel;
+import java.nio.channels.WritableByteChannel;
+import java.util.Collections;
+import java.util.HashSet;
 import java.util.Objects;
+import java.util.Set;
 
 final class CloseShieldChannelHandler implements InvocationHandler {
 
+    private static final Set<Class<?>> SUPPORTED_INTERFACES;
+
+    static {
+        final Set<Class<?>> interfaces = new HashSet<>();
+        interfaces.add(AsynchronousChannel.class);
+        interfaces.add(ByteChannel.class);
+        interfaces.add(Channel.class);
+        interfaces.add(GatheringByteChannel.class);
+        interfaces.add(InterruptibleChannel.class);
+        interfaces.add(NetworkChannel.class);
+        interfaces.add(ReadableByteChannel.class);
+        interfaces.add(ScatteringByteChannel.class);
+        interfaces.add(SeekableByteChannel.class);
+        interfaces.add(WritableByteChannel.class);
+        SUPPORTED_INTERFACES = Collections.unmodifiableSet(interfaces);
+    }
+
+    static boolean isSupported(final Class<?> interfaceClass) {
+        return SUPPORTED_INTERFACES.contains(interfaceClass);
+    }
+
     /**
      * Tests whether the given method is allowed to be called after the shield is closed.
      *

src/test/java/org/apache/commons/io/channels/CloseShieldChannelTest.java

@@ -34,15 +34,13 @@
 import static org.mockito.Mockito.when;
 
 import java.io.IOException;
-import java.nio.channels.AsynchronousByteChannel;
 import java.nio.channels.AsynchronousChannel;
 import java.nio.channels.ByteChannel;
 import java.nio.channels.Channel;
 import java.nio.channels.ClosedChannelException;
 import java.nio.channels.FileChannel;
 import java.nio.channels.GatheringByteChannel;
 import java.nio.channels.InterruptibleChannel;
-import java.nio.channels.MulticastChannel;
 import java.nio.channels.NetworkChannel;
 import java.nio.channels.ReadableByteChannel;
 import java.nio.channels.ScatteringByteChannel;
@@ -65,14 +63,11 @@ class CloseShieldChannelTest {
     static Stream<Class<? extends Channel>> testedInterfaces() {
         // @formatter:off
         return Stream.of(
-                AsynchronousByteChannel.class,
                 AsynchronousChannel.class,
                 ByteChannel.class,
                 Channel.class,
                 GatheringByteChannel.class,
                 InterruptibleChannel.class,
-                MulticastChannel.class,
-                NetworkChannel.class,
                 NetworkChannel.class,
                 ReadableByteChannel.class,
                 ScatteringByteChannel.class,