Summary

The following constructors from DatagramSocket and MulticastSocket don't specify their behaviour when no address has been specified, or null is passed as a parameter.

• DatagramSocket()

• DatagramSocket(int port)

• DatagramSocket(SocketAddress bindaddr)

• DatagramSocket(int port, InetAddress laddr)

• MulticastSocket()

• MulticastSocket(int port)

• MulticastSocket(SocketAddress bindaddr)

Problem

The behaviour of several DatagramSocket and MulticastSocket constructors is unspecified, or the specification of this behaviour is ambiguous, when no InetAddress is supplied, or null is passed as a parameter to the constructors that accept an InetAddress or SocketAddress.

Solution

Update the specification of the listed constructors to inform the user that the socket will be bound to the wildcard address when no InetAdress address is supplied or null is passed as a value for InetAddress. Similarly, if null is passed as a parameter for SocketAddress, an unbound socket will be created.

Specification

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

     /**
      * 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
      * with 0 as its argument to ensure the operation is allowed.
      * 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.
      *
      * @see SecurityManager#checkListen
      */
     public DatagramSocket() throws SocketException {

...

     /**
      * 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
      * with the port from the socket address
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
      * @param bindaddr local socket address to bind, or {@code null}
      *                 for an unbound socket.
      *
      * @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 bindaddr is a
      *              SocketAddress subclass not supported by this socket.
      *
      * @see SecurityManager#checkListen
      * @since   1.4
      */
     public DatagramSocket(SocketAddress bindaddr) throws SocketException {

...

     /**
      * 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
      * with the {@code port} argument
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
      * @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
      */
     public DatagramSocket(int port) throws SocketException {

...

     /**
      * Creates a datagram socket, bound to the specified local
      * 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.
+     * 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
      * with the {@code port} argument
      * as its argument to ensure the operation is allowed.
      * 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.
      * @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
      */
     public DatagramSocket(int port, InetAddress laddr) throws SocketException {

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

     /**
-     * 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
      * called with 0 as its argument to ensure the operation is allowed. This
      * could result in a SecurityException.
      * <p>
      * When the socket is created the
      * {@link DatagramSocket#setReuseAddress(boolean)} method is called to
      * enable the SO_REUSEADDR socket option.
      *
      * @throws    IOException if an I/O exception occurs while creating the
      * MulticastSocket
      * @throws    SecurityException if a security manager exists and its
      * {@code checkListen} method doesn't allow the operation.
      * @see SecurityManager#checkListen
      * @see java.net.DatagramSocket#setReuseAddress(boolean)
      * @see java.net.DatagramSocketImpl#setOption(SocketOption, Object)
      */
     public MulticastSocket() throws IOException {

...

     /**
-     * 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
      * with the {@code port} argument
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      * <p>
      * When the socket is created the
      * {@link DatagramSocket#setReuseAddress(boolean)} method is
      * called to enable the SO_REUSEADDR socket option.
      *
      * @param     port port to use
      * @throws    IOException if an I/O exception occurs
      *            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)
      */
     public MulticastSocket(int port) throws IOException {

...

      /**
-     * 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
      * with the SocketAddress port as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      * <p>
      * When the socket is created the
      * {@link DatagramSocket#setReuseAddress(boolean)} method is
      * called to enable the SO_REUSEADDR socket option.
      *
      * @param    bindaddr Socket address to bind to, or {@code null} for
      *           an unbound socket.
      * @throws   IOException if an I/O exception occurs
      *           while creating the MulticastSocket
      * @throws   SecurityException  if a security manager exists and its
      *           {@code checkListen} method doesn't allow the operation.
      * @see      SecurityManager#checkListen
      * @see      java.net.DatagramSocket#setReuseAddress(boolean)
      *
      * @since 1.4
      */
     public MulticastSocket(SocketAddress bindaddr) throws IOException {