Summary
-------

`DatagramSocket::send` doesn't specify what happens when the target address is not set in a `DatagramPacket` and the socket is not connected.
This CSR proposes to specify that `IllegalArgumentException` will be thrown.

Problem
-------
`DatagramSocket::send` doesn't specify what happens when the target address is not set in a `DatagramPacket` and the socket is not connected. By happenstance the current behavior is to throw `NullPointerException`.
Throwing `IllegalArgumentException` would however make more sense, and would be consistent with how `DatagramChannel` / `DatagramSocketAdaptor` handle this case.

Solution
--------

Alter the implementation of `DatagramSocket::send(DatagramPacket)` and the deprecated `MulticastSocket::send(DatagramPacket p, byte ttl)` to throw `IllegalArgumentException` in the case above. The API documentation of both method is updated to cover that case too.

Additionally, the implementation of the deprecated `MulticastSocket::send(DatagramPacket p, byte ttl)` is made consistent with 
`DatagramSocket::send(DatagramPacket)`. In the case where the socket is connected and the target address is different from that of the connected peer it will now throw `IllegalArgumentException` (just like `DatagramSocket`) instead of an undocumented `SecurityException`. It is also updated to specify that `PortUnreachableException` might be thrown, in the same way that `DatagramSocket::send` does.

Specification
-------------

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

          *             if this socket has an associated channel,
          *             and the channel is in non-blocking mode.
          * @throws     IllegalArgumentException if the socket is connected,
    -     *             and connected address and packet address differ.
    +     *             and connected address and packet address differ, or
    +     *             if the socket is not connected and the packet address
    +     *             is not set.
          *
          * @see        java.net.DatagramPacket
          * @see        SecurityManager#checkMulticast(InetAddress)
    @@ -655,12 +657,15 @@
          * @spec JSR-51
          */
         public void send(DatagramPacket p) throws IOException {

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

          * @param ttl optional time to live for multicast packet.
          * default ttl is 1.
          *
    -     * @throws    IOException is raised if an error occurs i.e
    -     * error while setting ttl.
    +     * @throws     IOException is raised if an error occurs i.e
    +     *             error while setting ttl.
          * @throws     SecurityException  if a security manager exists and its
          *             {@code checkMulticast} or {@code checkConnect}
          *             method doesn't allow the send.
    +     * @throws     PortUnreachableException may be thrown if the socket is connected
    +     *             to a currently unreachable destination. Note, there is no
    +     *             guarantee that the exception will be thrown.
    +     * @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.
    +     *
          *
          * @deprecated Use the following code or its equivalent instead:
          *  ......
          */
         public void send(DatagramPacket p, byte ttl) throws IOException {

For convenience the current webrev can be browsed here: http://cr.openjdk.java.net/~dfuchs/webrev_8233141/webrev.00/