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/