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) {