Update DatagramSocket to add support for joining multicast groups

Summary

Allow DatagramSocket to be used both for sending and receiving multicast datagrams. We propose to "move" joinGroup(SocketAddress, NetworkInterface) and leaveGroup(SocketAddress, NetworkInterface) up from MulticastSocket into DatagramSocket.

Problem

DatagramSocket has a DatagramSocket.setDatagramSocketImplFactory method that allows to globally replace the default DatagramSocket/MulticastSocket implementation provided by the JDK. This was provided as a way in early JDK releases to replace the system wide implementation. It has been mostly obsolete since Java 1.4. A DatagramSocket can be created to use a custom implementation by extending DatagramSocket and using the protected constructor that takes the impl as a parameter. However, MulticastSocket doesn't provide such a constructor.

Though DatagramSocket can be subclassed to provide a custom implementation, MulticastSocket, if subclassed, will still create its default implementation, even when all methods of MulticastSocket are overridden in order not to use it. This will create a file descriptor / socket leak.

The only solution to avoid that is currently to replace the default DatagramSocketImplFactory by calling the static DatagramSocket.setDatagramSocketImplFactory. We need a better solution.

Solution

The solution proposed in this change is to allow DatagramSocket to both send and receive multicast datagrams. An application that need to completely replace the default multicast implementation, and that cannot be easily updated to use DatagramChannel, can do so by subclassing DatagramSocket instead.

Specification

• move joinGroup(SocketAddress, NetworkInterface) and leaveGroup(SocketAddress, NetworkInterface) up from MulticastSocket into DatagramSocket.
• improve DatagramSocket with an API note to describe how DatgramSocket can be used directly for multicasting.
• add an @apiNote to the various convenience getters/setters defined in DatagramSocket and MulticastSocket to show how they map to standard socket options.

Overrides of the two methods hoisted to DatagramSocket are kept in MulticastSocket for the purpose of keeping @since properly documented.

A zip of the specdiff will be attached before this CSR is finalized. In the meantime, and for convenience, the specdiff can be browsed online at:

http://cr.openjdk.java.net/~dfuchs/ds-ms-8237352-specdiff.07/overview-summary.html