changeset 59492:4d5a58b0146f

8243507: DatagramSocket constructors don?t always specify what happens when passed invalid parameters Summary: This fix updates the spec for DatagramSocket's constructors to inform the user of the Exceptions thrown when an invalid argument is passed. Reviewed-by: dfuchs
author pconcannon
date Fri, 29 May 2020 11:08:09 +0100
parents f1f88e6fad02
children 41651bcb6923
files src/java.base/share/classes/java/net/DatagramSocket.java test/jdk/java/net/DatagramSocket/Constructor.java
diffstat 2 files changed, 81 insertions(+), 5 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/net/DatagramSocket.java	Thu May 28 22:34:02 2020 -0400
+++ b/src/java.base/share/classes/java/net/DatagramSocket.java	Fri May 29 11:08:09 2020 +0100
@@ -188,6 +188,8 @@
      *               or the socket could not bind to the specified local port.
      * @throws     SecurityException  if a security manager exists and its
      *             {@code checkListen} method doesn't allow the operation.
+     * @throws     IllegalArgumentException  if bindaddr is a
+     *              SocketAddress subclass not supported by this socket.
      *
      * @see SecurityManager#checkListen
      * @since   1.4
@@ -208,11 +210,13 @@
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
-     * @param      port port to use.
+     * @param      port local port to use in the bind operation.
      * @throws     SocketException  if the socket could not be opened,
      *               or the socket could not bind to the specified local port.
      * @throws     SecurityException  if a security manager exists and its
      *             {@code checkListen} method doesn't allow the operation.
+     * @throws     IllegalArgumentException  if port is <a href="#PortRange">
+     *              out of range.</a>
      *
      * @see SecurityManager#checkListen
      */
@@ -222,7 +226,11 @@
 
     /**
      * Creates a datagram socket, bound to the specified local
-     * address.  The local port must be between 0 and 65535 inclusive.
+     * address.
+     * <p><a id="PortRange"></a>The local port must be between 0 and
+     * 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.
@@ -233,13 +241,15 @@
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
-     * @param port local port to use
+     * @param port local port to use in the bind operation.
      * @param laddr local address to bind
      *
      * @throws     SocketException  if the socket could not be opened,
      *               or the socket could not bind to the specified local port.
      * @throws     SecurityException  if a security manager exists and its
      *             {@code checkListen} method doesn't allow the operation.
+     * @throws     IllegalArgumentException  if port is <a href="#PortRange">
+     *              out of range.</a>
      *
      * @see SecurityManager#checkListen
      * @since   1.1
@@ -311,7 +321,8 @@
      * @param port the remote port for the socket.
      *
      * @throws IllegalArgumentException
-     *         if the address is null, or the port is out of range.
+     *         if the address is null, or the port is <a href="#PortRange">
+     *         out of range.</a>
      *
      * @throws SecurityException
      *         if a security manager has been installed and it does
@@ -504,7 +515,8 @@
      * @throws     IllegalArgumentException if the socket is connected,
      *             and connected address and packet address differ, or
      *             if the socket is not connected and the packet address
-     *             is not set or if its port is out of range.
+     *             is not set or if its port is <a href="#PortRange">out of
+     *             range.</a>
      *
      * @see        java.net.DatagramPacket
      * @see        SecurityManager#checkMulticast(InetAddress)
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/test/jdk/java/net/DatagramSocket/Constructor.java	Fri May 29 11:08:09 2020 +0100
@@ -0,0 +1,64 @@
+/*
+ * 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 8243507
+ * @summary Checks to ensure that DatagramSocket constructors throw expected
+ *          exceptions.
+ * @run testng Constructor
+ */
+
+import org.testng.annotations.Test;
+
+import java.net.DatagramSocket;
+import java.net.InetAddress;
+import java.net.SocketAddress;
+
+import static org.testng.Assert.assertThrows;
+
+public class Constructor {
+    private static final InetAddress LOOPBACK =
+            InetAddress.getLoopbackAddress();
+    private static final Class<IllegalArgumentException> IAE =
+            IllegalArgumentException.class;
+
+    private class TestSocketAddress extends SocketAddress {
+        TestSocketAddress() {}
+    }
+
+    @Test
+    public void testBindAddress() {
+        var addr = new TestSocketAddress();
+        assertThrows(IllegalArgumentException.class,
+                () -> new DatagramSocket(addr));
+    }
+
+    @Test
+    public void testInvalidPortRange() {
+        var invalidPortValues = new int[] {-1, 65536, Integer.MAX_VALUE};
+        for (int i : invalidPortValues) {
+            assertThrows(IAE, () -> new DatagramSocket(i));
+            assertThrows(IAE, () -> new DatagramSocket(i, LOOPBACK));
+        }
+    }
+}