Behaviors of DatagramSocket/DatagramChannel::socket send methods are not always consistent

Summary

The behaviour of the send methods for DatagramSocket, MulticastSocket, DatagramChannel and DatagramSocketAdaptor are not always consistent when given a DatagramPacket with invalid details. The specification of DatagramSocket/MulticastSocket doesn't cover all the cases.

Problem

Each of the Socket types described above throw different exceptions when supplied with a DatagramPacket with an invalid port number (negative or greater than 0xFFFF).

Solution

Specify that IllegalArgumentException should be thrown is the supplied port is out of range. This is what the DatagramChannel::socket already does, but the behavior of DatagramSocket and MulticastSocket is currently system dependent. The solution proposed here is to align the behavior of DatagramSocket and MulticastSocket send methods to that of connect(InetAddress, port) and throw IllegalArgumentException premptively before calling the underlying native implementation. This will also align the behavior of DatagramSocket and MulticastSocket to that of the DatagramChannel::socket adapter.

Specification

java/net/DatagramSocket.java

      * @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.
+     *             is not set or if its port is out of range.
      *
      * @see        java.net.DatagramPacket
      * @see        SecurityManager#checkMulticast(InetAddress)
      * @see        SecurityManager#checkConnect
      * @revised 1.4
      * @spec JSR-51
      */
     public void send(DatagramPacket p) throws IOException  {

java/net/MulticastSocket.java

     * @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
-    *             ls not set.
+    *             is not set or if its port is out of range.
     *
     *
     * @deprecated Use the following code or its equivalent instead:
     *  ......
     *  int ttl = mcastSocket.getTimeToLive();
     *  mcastSocket.setTimeToLive(newttl);
     *  mcastSocket.send(p);
     *  mcastSocket.setTimeToLive(ttl);
     *  ......
     *
     * @see DatagramSocket#send
     * @see DatagramSocket#receive
     * @see SecurityManager#checkMulticast(java.net.InetAddress, byte)
     * @see SecurityManager#checkConnect
     */
    @Deprecated
    public void send(DatagramPacket p, byte ttl)