Bug ID: JDK-8233342 (dc spec) connect and disconnect methods should specify that they may block

Type: CSR
Component: core-libs
Sub-Component: java.nio

Priority: P4
Status: Closed
Resolution: Approved
Fix Versions: 14

Submitted: 2019-10-31
Updated: 2019-11-14
Resolved: 2019-11-14

Summary
-------

Update specification of `java.nio.channels.DatagramChannel` methods `connect` and `disconnect` to indicate that they may block.

Problem
-------

The `DatagramChannel` methods `connect` and `disconnect` may block if a read or write operation is in progress on the channel when they are invoked, but the specification does not state that this is the case.

Solution
--------

Modify verbiage in `DatagramChannel.connect` and `DatagramChannel.disconnect` to indicate that they may block if a read or write operation is in progress at the moment they are invoked.

Specification
-------------

* `connect`

Add this verbiage:

```Datagrams in the channel's {@linkplain java.net.StandardSocketOptions#SO_RCVBUF socket receive buffer}, which have not been {@linkplain #receive(ByteBuffer) received} before invoking this method, may be discarded.```

```If another thread has already initiated a read or write operation upon this channel, then an invocation of this method will block until any such operation is complete.```

Remove this verbiage:

```It will not have any effect on read or write operations that are already in progress at the moment that it is invoked.```

* `disconnect`

Add this sentence:

```If another thread has already initiated a read or  write operation upon this channel, then an invocation of this method may block until any such operation is complete.```

Remove this verbiage:

```It will not have any effect on read or write operations that are already in progress at the moment that it is invoked.```

Please also refer to the (newest) attached webrev `webrev-8146298.zip`.

Moving to Approved.
14-11-2019
I recommend a normative statement like An implementation many discard any and all datagrams received prior to connecting the channel's socket. paired with an implNote about the JDK implementation.
06-11-2019
I agree with Alan that this is an implementation detail. The note is however useful for a user of the API, who might e.g. use the information to debug and better understand the correlation between network and application logs.
05-11-2019
DatagramChannel is abstract but cannot be extended and implemented in isolation. It is tied to a SelectorProvider. The unit of replacement is the entire ball of wax that is the SelectorProvider and all SelectableChannel channel implementations. I'm not aware of any implementations outside of the JDK. The note for the javadoc that is proposed is here is not meant to be normative, it is meant to be an informative note to document JDK-specific behavior. An alternative implementation (if it existed) could implement it via emulation and in a way that does not require discarding the datagrams that are in the socket receive buffer. The implNote that we need in the javadoc is to simply say that in the JDK implementation, connecting the channel's socket will discard any datagrams in the socket's receive buffer.
05-11-2019
As an abstract class, users will be interacting with objects that are instances of some subtype of DatagramChannel, perhaps a subtype of their own creation. The connect and disconnect methods are both abstract, in particular, they are not final. The @implNote is not inherited by overrides of these methods. In that context, my understanding is that the intention of "Any datagrams received prior to connecting the channel's socket are discarded." means either: 1) For any subtypes of this class that override this method, datagrams may be discarded as described. 2) For all subtypes of this class, datagrams must be discarded as described. Either statement would be a full normative spec change and not merely informative note. Per JDK-8068562 @implNote is only informative. Is my understanding incorrect?
04-11-2019
The statement is about the JDK implementation. It could be tweaked in many ways. The intention is to communicate that all datagrams in the socket receive buffer, that have not been received, are discarded. This is long standing behavior and motivated by both security and maintainability reasons.
04-11-2019
Is "@implNote Any datagrams received prior to connecting the channel's socket are discarded." a statement about all implementations, or just one allowable behavior? My sense is @impleNote doesn't carry the right intention here.
04-11-2019