Summary

Some implementations of the connect methods for DatagramSocket may cause datagrams in the socket receive buffer to be discarded if not previously received via a call to DatagramSocket.receive. This is notably the case with the DatagramSocket returned by DatagramChannel::socket, and also now with the new DatagramSocket implementation in JDK 15 that relies on it, as was highlighted in JEP 373 "Risk and Assumptions" section.

• DatagramSocket.connect(SocketAddress addr)

• DatagramSocket.connect(InetAddress address, int port)

Problem

The javadoc for the connect methods in DatagramSocket should inform the user of this possible behaviour when they have datagrams in their the socket receive buffer when these methods are first called.

Solution

To update the javadoc connect methods for DatagramSocket to highlight what may happen to the datagrams that may currently reside in the DatagramSocket's socket receive buffer if DatagramSocket.receive is not called first.

Specification

java/net/DatagramSocket.java

     /**
      * Connects this socket to a remote socket address (IP address + port number).
      *
      * <p> If given an {@link InetSocketAddress InetSocketAddress}, this method
      * behaves as if invoking {@link #connect(InetAddress,int) connect(InetAddress,int)}
      * with the given socket addresses IP address and port number, except that the
      * {@code SocketException} that may be raised is not wrapped in an
-     * {@code UncheckedIOException}.
+     * {@code UncheckedIOException}. Datagrams in the socket's {@linkplain
+     * java.net.StandardSocketOptions#SO_RCVBUF socket receive buffer}, which
+     * have not been {@linkplain #receive(DatagramPacket) received} before invoking
+     * this method, may be discarded.
      *
      * @param   addr    The remote address.
      *
      * @throws  SocketException
      *          if the connect fails
      *
      * @throws IllegalArgumentException
      *         if {@code addr} is {@code null}, or {@code addr} is a SocketAddress
      *         subclass not supported by this socket
      *
      * @throws SecurityException
      *         if a security manager has been installed and it does
      *         not permit access to the given remote address
      *
      * @since 1.4
      */
     public void connect(SocketAddress addr) throws SocketException {

...

      * any security checks</b> on incoming and outgoing packets, other than
      * matching the packet's and the socket's address and port. On a send
      * operation, if the packet's address is set and the packet's address
      * and the socket's address do not match, an {@code IllegalArgumentException}
      * will be thrown. A socket connected to a multicast address may only
-     * be used to send packets.
+     * be used to send packets. Datagrams in the socket's {@linkplain
+     * java.net.StandardSocketOptions#SO_RCVBUF socket receive buffer}, which
+     * have not been {@linkplain #receive(DatagramPacket) received} before invoking
+     * this method, may be discarded.
      *
      * @param address the remote address for the socket
      *
      * @param port the remote port for the socket.
      *
      * @throws IllegalArgumentException
      *         if the address is null, or the port is <a href="#PortRange">
      *         out of range.</a>
      *
      * @throws SecurityException
      *         if a security manager has been installed and it does
      *         not permit access to the given remote address
      *
      * @throws UncheckedIOException
      *         may be thrown if connect fails, for example, if the
      *         destination address is non-routable
      *
      * @see #disconnect
      *
      * @since 1.2
      */
     public void connect(InetAddress address, int port) {