Summary

Several constructors of DatagramSocket don't specify what happens when passed invalid parameters.

Problem

Currently, the DatagramSocket constructor DatagramSocket(SocketAddress bindaddr) doesn't specify what happens if passed a SocketAddress subclass not supported by this socket. Also, there are two DatagramSocket constructors -- DatagramSocket(int) and DatagramSocket(int, InetAddress) -- that accept a port number, but neither constructor specifies what happens when passed port 0, or a port which falls outside of the valid range of port numbers i.e between 0 and 65535 inclusive.

Solution

This fix updates the spec for each these constructors to inform the user of what happens when passed an invalid argument such as the ones described above. An IllegalArgumentException is thrown when passed an invalid port, or, if zero is passed, that the system will choose an appropriate port for them. An IllegalArgumentException will also be thrown if an invalid SocketAddress subclass is passed as a parameter.

Specification

     /**
      * 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.
      *
      * <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
+     * @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
      */
     public DatagramSocket(int port, InetAddress laddr) throws SocketException  {

...

-    * @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
     */
    public DatagramSocket(int port) throws SocketException {

...

     * @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 {