8243999: DatagramSocket and MulticastSocket constructors don't specify how a null InetAddress is handled

This fix clarifies the behaviours of constructors from DatagramSocket and MulticastSocket when no address or a null address is supplied.

Reviewed-by: dfuchs

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

@@ -138,8 +138,7 @@ public class DatagramSocket implements java.io.Closeable {
     /**
      * Constructs a datagram socket and binds it to any available port
      * on the local host machine.  The socket will be bound to the
-     * {@link InetAddress#isAnyLocalAddress wildcard} address,
-     * an IP address chosen by the kernel.
+     * {@link InetAddress#isAnyLocalAddress wildcard} address.
      *
      * <p>If there is a security manager,
      * its {@code checkListen} method is first called
@@ -147,7 +146,7 @@ public class DatagramSocket implements java.io.Closeable {
      * This could result in a SecurityException.
      *
      * @throws     SocketException  if the socket could not be opened,
-     *               or the socket could not bind to the specified local port.
+     *              or the socket could not be bound.
      * @throws     SecurityException  if a security manager exists and its
      *             {@code checkListen} method doesn't allow the operation.
      *
@@ -173,7 +172,7 @@ public class DatagramSocket implements java.io.Closeable {
      * Creates a datagram socket, bound to the specified local
      * socket address.
      * <p>
-     * If, if the address is {@code null}, creates an unbound socket.
+     * If the address is {@code null} an unbound socket will be created.
      *
      * <p>If there is a security manager,
      * its {@code checkListen} method is first called
@@ -201,8 +200,7 @@ public class DatagramSocket implements java.io.Closeable {
     /**
      * Constructs a datagram socket and binds it to the specified port
      * on the local host machine.  The socket will be bound to the
-     * {@link InetAddress#isAnyLocalAddress wildcard} address,
-     * an IP address chosen by the kernel.
+     * {@link InetAddress#isAnyLocalAddress wildcard} address.
      *
      * <p>If there is a security manager,
      * its {@code checkListen} method is first called
@@ -231,9 +229,9 @@ public class DatagramSocket implements java.io.Closeable {
      * 65535 inclusive. A port number of {@code zero} will let the system pick
      * up an ephemeral port in a {@code bind} operation.
      * <p>
-     * If the IP address is 0.0.0.0, the socket will be bound to the
-     * {@link InetAddress#isAnyLocalAddress wildcard} address,
-     * an IP address chosen by the kernel.
+     * If the IP address is a {@link InetAddress#isAnyLocalAddress wildcard}
+     * address, or is {@code null}, the socket will be bound to the wildcard
+     * address.
      *
      * <p>If there is a security manager,
      * its {@code checkListen} method is first called
@@ -242,7 +240,7 @@ public class DatagramSocket implements java.io.Closeable {
      * This could result in a SecurityException.
      *
      * @param port local port to use in the bind operation.
-     * @param laddr local address to bind
+     * @param laddr local address to bind (can be {@code null})
      *
      * @throws     SocketException  if the socket could not be opened,
      *               or the socket could not bind to the specified local port.

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

@@ -147,7 +147,9 @@ public class MulticastSocket extends DatagramSocket {
 
 
     /**
-     * Create a multicast socket.
+     * Constructs a multicast socket and binds it to any available port
+     * on the local host machine.  The socket will be bound to the
+     * {@link InetAddress#isAnyLocalAddress wildcard} address.
      *
      * <p>
      * If there is a security manager, its {@code checkListen} method is first
@@ -171,7 +173,9 @@ public class MulticastSocket extends DatagramSocket {
     }
 
     /**
-     * Create a multicast socket and bind it to a specific port.
+     * Constructs a multicast socket and binds it to the specified port
+     * on the local host machine. The socket will be bound to the
+     * {@link InetAddress#isAnyLocalAddress wildcard} address.
      *
      * <p>If there is a security manager,
      * its {@code checkListen} method is first called
@@ -188,6 +192,9 @@ public class MulticastSocket extends DatagramSocket {
      *            while creating the MulticastSocket
      * @throws    SecurityException  if a security manager exists and its
      *            {@code checkListen} method doesn't allow the operation.
+     * @throws    IllegalArgumentException  if port is  <a href="DatagramSocket.html#PortRange">
+     *            out of range.</a>
+     *
      * @see       SecurityManager#checkListen
      * @see       java.net.DatagramSocket#setReuseAddress(boolean)
      */
@@ -196,9 +203,10 @@ public class MulticastSocket extends DatagramSocket {
     }
 
     /**
-     * Create a MulticastSocket bound to the specified socket address.
+     * Creates a multicast socket, bound to the specified local
+     * socket address.
      * <p>
-     * Or, if the address is {@code null}, create an unbound socket.
+     * If the address is {@code null} an unbound socket will be created.
      *
      * <p>If there is a security manager,
      * its {@code checkListen} method is first called

test/jdk/java/net/DatagramSocket/Constructor.java

@@ -22,28 +22,28 @@
  */
 
 /* @test
- * @bug 8243507
- * @summary Checks to ensure that DatagramSocket constructors throw expected
- *          exceptions.
+ * @bug 8243507 8243999
+ * @summary Checks to ensure that DatagramSocket constructors behave as expected
  * @run testng Constructor
  */
 
 import org.testng.annotations.Test;
 
+import java.io.IOException;
 import java.net.DatagramSocket;
 import java.net.InetAddress;
 import java.net.SocketAddress;
 
 import static org.testng.Assert.assertThrows;
+import static org.testng.Assert.assertTrue;
 
 public class Constructor {
-    private static final InetAddress LOOPBACK =
-            InetAddress.getLoopbackAddress();
-    private static final Class<IllegalArgumentException> IAE =
-            IllegalArgumentException.class;
+    private static final InetAddress LOOPBACK = InetAddress.getLoopbackAddress();
+    private static final Class<IllegalArgumentException> IAE = IllegalArgumentException.class;
 
     private class TestSocketAddress extends SocketAddress {
-        TestSocketAddress() {}
+        TestSocketAddress() {
+        }
     }
 
     @Test
@@ -55,10 +55,25 @@ public class Constructor {
 
     @Test
     public void testInvalidPortRange() {
-        var invalidPortValues = new int[] {-1, 65536, Integer.MAX_VALUE};
+        var invalidPortValues = new int[]{-1, 65536, Integer.MAX_VALUE};
         for (int i : invalidPortValues) {
             assertThrows(IAE, () -> new DatagramSocket(i));
             assertThrows(IAE, () -> new DatagramSocket(i, LOOPBACK));
         }
     }
+
+    @Test
+    public void testDSNullAddress() throws IOException {
+        try (var ds = new DatagramSocket()) {
+            assertTrue(ds.getLocalAddress().isAnyLocalAddress());
+        }
+
+        try (var ds1 = new DatagramSocket(null)) {
+            assertTrue(ds1.getLocalAddress().isAnyLocalAddress());
+        }
+
+        try (var ds2 = new DatagramSocket(0, null)) {
+            assertTrue(ds2.getLocalAddress().isAnyLocalAddress());
+        }
+    }
 }

test/jdk/java/net/MulticastSocket/Constructor.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/* @test
+ * @bug 8243999
+ * @summary Checks to ensure that Multicast constructors behave as expected
+ * @run testng Constructor
+ */
+
+import org.testng.annotations.Test;
+
+import java.io.IOException;
+import java.net.MulticastSocket;
+
+import static org.testng.Assert.assertTrue;
+
+public class Constructor {
+    @Test
+    public void testMSNullAddress() throws IOException {
+        try (var ms = new MulticastSocket()) {
+            assertTrue(ms.getLocalAddress().isAnyLocalAddress());
+        }
+
+        try (var ms1 = new MulticastSocket(null)) {
+            assertTrue(ms1.getLocalAddress().isAnyLocalAddress());
+        }
+    }
+}