Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8276968

(ch) InputStream returned by Channels.newInputStream should have fast path for SelectableChannels

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No behavior change, this is a docs only update to align the API docs with the implementation.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              mkarg Markus Karg
              Reporter:
              mkarg Markus Karg
              Reviewed By:
              Alan Bateman, Brian Burkhalter
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: