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

(se spec) SelectionKey.OP_READ/OP_WRITE documentation errors



    • Bug
    • Resolution: Fixed
    • P4
    • 15
    • 1.4.0, 15
    • core-libs
    • b14
    • sparc
    • solaris_8


      Name: nt126004 Date: 12/21/2001

      Documentation for java.nio.SelectionKey.OP_READ states:

      'If the selector detects that the corresponding channel is
      ready for reading, has reached end-of-stream, has been
      remotely shut down for further reading, or has an
      error pending, then it will add OP_READ to the key's
      ready-operation set and add the key to its selected-key

      Part of this makes no sense. Clearly 'shut down for further
      reading' should be '... writing'.
      The documentation already says 'has reached
      end of stream. It doesn't need to say any more than that, because remote close
      and remote shutdownOutput are completely equivalent from the point of view of
      the reader, & both produce end-of-stream.

      Similarly the documentation for OP_WRITE states: ' ... for
      further writing'. This is also back-to-front, but in this
      case it should *not* be 'remotely shut down for further
      reading', it should be 'closed at the remote end', because
      Socket.shutdownInput() cannot be detected remotely (there is
      no network protocol for this event, and the remote TCP stack
      continues to acknowledge but ignore further input). OP_WRITE needs to say 'closed by the
      remote end', which it doesn't say, and it mustn't say anything about shutdown
      whatsoever, which would be incorrect, as remote shutdownInput is not detectable
      and does not produce the OP_WRITE selection event (neither does remote
      shutdownOutput). Talking about shutdown here is just irrelevant and confusing;
      shutdown has a specific meaning in sockets and shouldn't be used as a vague
      generic term.

      There is also a design issue. Why isn't OP_ERROR supported,
      which would provide a means of selecting for out-of-band data?
      This would be part of supporting OOB data better, which there may
      be zero demand for. It just maps to the third set of FDs passed to select():
      should probably be OP_EXCEPTION instead, and manifest itself as
      SelectionKey.isException(). For a socket the condition is triggered when OOB
      data arrives and OOB_INLINE is not set. See e.g. Stevens Unix Network
      Programming 2nd ed. vol I #6.3 p151, or Stevens & Wright TCP/IP Illustrated Vol
      II #16.13 p 524. If you are ever going to support OOB more fully than at
      present (OOB_INLINE only) you will have to add this. (You would also have to
      add byte Socket.receiveOOBData() throws IOException, which would only work if
      OOB data was available and OOB_INLINE wasn't set.)
      (Review ID: 137437)


        Issue Links



              bpb Brian Burkhalter
              nthompsosunw Nathanael Thompson (Inactive)
              0 Vote for this issue
              1 Start watching this issue