Summary

Update java.nio.channels.Channels.newInputStream(ReadableByteChannel) to document that the transferTo method of the returned input stream will throw IllegalBlockingModeException if the channel is configured non-blocking. The method has always documented that the exception is thrown by the read methods.

Problem

java.io.InputStream.transferTo(OutputStream) was added in Java 9. It's a blocking operation. We missed amending Channels.newInputStream's method description to specify that transferTo throws IllegalBlockingModeException if the channel is configured non-blocking.

Solution

Update the method description to document that IllegalBlockingModeException is thrown when the channel is configured non-blocking.

There is no behavior change as the implementation already throws IllegalBlockingModeException (this behaviour goes back to Java 9 when the transferTo method was added).

Specification

We propose to change the method description as follows:

diff --git a/src/java.base/share/classes/java/nio/channels/Channels.java b/src/java.base/share/classes/java/nio/channels/Channels.java
index 2d1637c5369..3e68d49b2b7 100644
--- a/src/java.base/share/classes/java/nio/channels/Channels.java
+++ b/src/java.base/share/classes/java/nio/channels/Channels.java
@@ -69,9 +69,12 @@ public final class Channels {
     /**
      * Constructs a stream that reads bytes from the given channel.
      *
-     * <p> The {@code read} methods of the resulting stream will throw an
-     * {@link IllegalBlockingModeException} if invoked while the underlying
-     * channel is in non-blocking mode.  The stream will not be buffered, and
+     * <p> The {@code read} and {@code transferTo} methods of the resulting stream
+     * will throw an {@link IllegalBlockingModeException} if invoked while the
+     * underlying channel is in non-blocking mode. The {@code transferTo} method
+     * will also throw an {@code IllegalBlockingModeException} if invoked to
+     * transfer bytes to an output stream that writes to an underlying channel in
+     * non-blocking mode.  The stream will not be buffered, and
      * it will not support the {@link InputStream#mark mark} or {@link
      * InputStream#reset reset} methods.  The stream will be safe for access by
      * multiple concurrent threads.  Closing the stream will in turn cause the