8233191: MulticastSocket joinGroup/leaveGroup do not specify their behavior when the outgoing interface has not been set

Clarifies the behaviour of 2-arg joinGroup/leaveGroup methods when null is passed for the NetworkInteface argument. The fix also clarifies what is returned by getInterface() and getNetworkInterface() methods when no previous NetworkInterface has been set.

Reviewed-by: alanb, chegar, dfuchs

Author: pconcannon

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

@@ -29,7 +29,6 @@
 import java.util.Collections;
 import java.util.Enumeration;
 import java.util.Set;
-
 /**
  * The multicast datagram socket class is useful for sending
  * and receiving IP multicast packets. A MulticastSocket is
@@ -378,15 +377,18 @@ public void leaveGroup(InetAddress mcastaddr) throws IOException {
      *
      * @param  mcastaddr is the multicast address to join
      * @param  netIf specifies the local interface to receive multicast
-     *         datagram packets, or <i>null</i> to defer to the interface set by
+     *         datagram packets, or {@code null} to defer to the interface set by
      *         {@link MulticastSocket#setInterface(InetAddress)} or
-     *         {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
+     *         {@link MulticastSocket#setNetworkInterface(NetworkInterface)}.
+     *         If {@code null}, and no interface has been set, the behaviour is
+     *         unspecified: any interface may be selected or the operation may fail
+     *         with a {@code SocketException}.
      * @throws IOException if there is an error joining, or when the address
      *         is not a multicast address, or the platform does not support
      *         multicasting
      * @throws SecurityException if a security manager exists and its
      *         {@code checkMulticast} method doesn't allow the join.
-     * @throws IllegalArgumentException if mcastaddr is null or is a
+     * @throws IllegalArgumentException if mcastaddr is {@code null} or is a
      *         SocketAddress subclass not supported by this socket
      * @see    SecurityManager#checkMulticast(InetAddress)
      * @since  1.4
@@ -423,15 +425,18 @@ public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
      * {@code mcastaddr} argument as its argument.
      *
      * @param  mcastaddr is the multicast address to leave
-     * @param  netIf specifies the local interface or <i>null</i> to defer
+     * @param  netIf specifies the local interface or {@code null} to defer
      *         to the interface set by
      *         {@link MulticastSocket#setInterface(InetAddress)} or
-     *         {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
+     *         {@link MulticastSocket#setNetworkInterface(NetworkInterface)}.
+     *         If {@code null}, and no interface has been set, the behaviour
+     *         is unspecified: any interface may be selected or the operation
+     *         may fail with a {@code SocketException}.
      * @throws IOException if there is an error leaving or when the address
      *         is not a multicast address.
      * @throws SecurityException if a security manager exists and its
      *         {@code checkMulticast} method doesn't allow the operation.
-     * @throws IllegalArgumentException if mcastaddr is null or is a
+     * @throws IllegalArgumentException if mcastaddr is {@code null} or is a
      *         SocketAddress subclass not supported by this socket.
      * @see    SecurityManager#checkMulticast(InetAddress)
      * @since  1.4
@@ -491,7 +496,9 @@ public void setInterface(InetAddress inf) throws SocketException {
      * multicast packets.
      *
      * @return     An {@code InetAddress} representing the address
-     *             of the network interface used for multicast packets.
+     *             of the network interface used for multicast packets,
+     *             or if no interface has been set, an {@code InetAddress}
+     *             representing any local address.
      * @throws     SocketException if there is an error in the
      *             underlying protocol, such as a TCP error.
      * @deprecated The network interface may not be uniquely identified by
@@ -573,11 +580,13 @@ public void setNetworkInterface(NetworkInterface netIf)
     /**
      * Get the multicast network interface set.
      *
-     * @throws    SocketException if there is an error in
-     * the underlying protocol, such as a TCP error.
-     * @return the multicast {@code NetworkInterface} currently set
-     * @see #setNetworkInterface(NetworkInterface)
-     * @since 1.4
+     * @throws SocketException if there is an error in
+     *         the underlying protocol, such as a TCP error.
+     * @return The multicast {@code NetworkInterface} currently set. A placeholder
+     *         NetworkInterface is returned when there is no interface set; it has
+     *         a single InetAddress to represent any local address.
+     * @see    #setNetworkInterface(NetworkInterface)
+     * @since  1.4
      */
     public NetworkInterface getNetworkInterface() throws SocketException {
         NetworkInterface ni