Name: nt126004 Date: 12/21/2001


A DESCRIPTION OF THE PROBLEM :
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
set.'

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)
======================================================================