Summary

java.nio.channels.DatagramChannel::socket returns a java.net.DatagramSocket that allows code using the DatagramSocket API to access the channel's socket using the legacy API. This CSR proposes to remove a statement from the socket method's javadoc to allow for changes to the implementation, in particular to allow the implementation to return a java.net.MulticastSocket (a sub-class of DatagramSocket).

Problem

DatagramChannel::socket specifies that the returned object (a non-exposed subclass of DatagramSocket) does not declare any public methods beyond those specified by DatagramSocket. This statement is testable and prevents implementations from implementing additional interfaces beyond those implemented by DatagramSocket, or extending it in other ways that define additional public methods.

Solution

Remove the statement from the javadoc that the returned object doesn't declare any public methods beyond those declared by DatagramSocket.

Change the implementation to return a java.net.MulticastSocket (a sub-class of DatagramSocket). We do not propose to document (in an @implNote or elsewhere) that the returned object is an instance of MulticastSocket. Users of the API may of course discover this and cast to java.net.MulticastSocket of course but it seems unlikely given that MulticastSocket is legacy with many deprecated methods.

Specification

Remove the following statement from the DatagramChannel:socket specification:

"The returned object will not declare any public methods that are not declared in the java.net.DatagramSocket class."