From 12e43e216e7c87292ea34b5f44ec1676858d16c5 Mon Sep 17 00:00:00 2001 From: Patrick Concannon Date: Mon, 9 Dec 2019 15:54:44 +0000 Subject: [PATCH] 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 --- .../classes/java/net/MulticastSocket.java | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/src/java.base/share/classes/java/net/MulticastSocket.java b/src/java.base/share/classes/java/net/MulticastSocket.java index a7cac8f31f1..158c4196837 100644 --- a/src/java.base/share/classes/java/net/MulticastSocket.java +++ b/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 null 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 null 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