Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8247181

DatagramSocket.connect does not specify that it may cause datagrams in the socket receive buffer to be discarded

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 15
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      This specification change clarifies pre-existing behaviour of the `connect` methods for `DatagramSocket`
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              pconcannon Patrick Concannon (Inactive)
              Reporter:
              pconcannon Patrick Concannon (Inactive)
              Reviewed By:
              Chris Hegarty, Daniel Fuchs
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: