Summary

Update MulticastSocket documentation to clarify its relationship with DatagramSocket, and update code samples.

Problem

DatagramSocket has been updated by JDK-8237352 to support joining multicast group. This changes the relationship between DatagramSocket and MulticastSocket. The documentation of MulticastSocket should be updated to reflect this change.

Solution

Replace the first sentence in the MulticastSocket class level API doc with a more accurate description of the purpose of MulticastSocket. Fixed mistake in the following code sample too.

Specification

src/java.base/share/classes/java/net/MulticastSocket.java

 /**
- * The multicast datagram socket class is useful for sending
- * and receiving IP multicast packets. A MulticastSocket is
- * a (UDP) DatagramSocket, with additional capabilities for
- * joining "groups" of other multicast hosts on the internet.
+ * A {@code MulticastSocket} is a datagram socket that is
+ * convenient for sending and receiving IP multicast datagrams.
+ * The {@code MulticastSocket} constructors create a socket
+ * with appropriate socket options enabled that make
+ * it suitable for receiving multicast datagrams.
+ * The {@code MulticastSocket} class additionally defines
+ * convenient setter and getter methods for socket options
+ * that are commonly used by multicasting applications.
+ * <P>
+ * Joining one or more multicast groups makes it possible to
+ * receive multicast datagrams sent to these groups.
  * <P>
- * A multicast group is specified by a class D IP address
+ * An IPv4 multicast group is specified by a class D IP address
  * and by a standard UDP port number. Class D IP addresses
  * are in the range {@code 224.0.0.0} to {@code 239.255.255.255},
  * inclusive. The address 224.0.0.0 is reserved and should not be used.
  * <P>
  * One would join a multicast group by first creating a MulticastSocket
  * with the desired port, then invoking the
- * <CODE>joinGroup(InetAddress groupAddr)</CODE>
- * method:
+ * <CODE>joinGroup</CODE> method, specifying the group address and
+ * the network interface through which multicast datagrams will be
+ * received:
  * <PRE>{@code
  * // join a Multicast group and send the group salutations
  * ...
  * String msg = "Hello";
  * InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
- * InetSocketAddress group = new InetSocketAddress(mcastaddr, port);
+ * InetSocketAddress group = new InetSocketAddress(mcastaddr, 6789);
  * NetworkInterface netIf = NetworkInterface.getByName("bge0");
  * MulticastSocket s = new MulticastSocket(6789);
  *
- * s.joinGroup(group, netIf);
+ * s.joinGroup(new InetSocketAddress(mcastaddr, 0), netIf);
  * byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8);
- * DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length,
- *                                        group, 6789);
+ * DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, group);
  * s.send(hi);
  * // get their responses!
  * byte[] buf = new byte[1000];
  * DatagramPacket recv = new DatagramPacket(buf, buf.length);
  * s.receive(recv);