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

Summary

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

Problem

The current javadoc is unclear on the behaviour of the 2-arg joinGroup/leaveGroup methods if null is given for the NetworkInterface parameter and no interface has been set. Similarly, the javadoc for the methods getInterface() and getNetworkInterface() do not specify what is returned when no NetworkInterface has previously been set.

Solution

This fix clarifies the javadoc by describing the behaviour of the methods when null is passed for the NetworkInterface parameter for the 2-arg joinGroup/leaveGroup methods. It also clarifies what is returned from getInterface and getNetworkInterface when no NetworkInterface has been previously set.

Specification

MulticastSocket::joinGroup

      * @param netIf specifies the local interface to receive multicast
      *        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} is given and no interface has been set, the behaviour is
+     *        unspecified: any interface may be selected or the operation may fail
+     *        with a SocketException.

MulticastSocket::leaveGroup

      * @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)}
+     *        to the interface set by {@link MulticastSocket#setInterface(InetAddress)}
+     *        or {@link MulticastSocket#setNetworkInterface(NetworkInterface)}. If
+     *        {@code null} is given and no interface has been set, the behaviour is
+     *        unspecified: any interface may be selected or the operation may fail
+     *        with a SocketException.

MulticastSocket::getInterface

     * @return An {@code InetAddress} representing
      *  the address of the network interface used for
-     *  multicast packets.
-     *
+     *  multicast packets, or if no interface has been set,
+     *  an {@code InetAddress} representing any local address.

MulticastSocket::getNetworkInterface

-     * @return the multicast {@code NetworkInterface} currently set
+     * @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.