Summary

DatagramChannel::connect has useful undocumented behavior, which allows the local address of a connected DatagramChannel to be determined when the channel is bound to the wildcard address. This change documents the behavior.

The same behavior exists and is being documented in java.net.DatagramSocket

Problem

As in summary

Solution

The solution is to document the behavior in the java.nio.channels.DatagramChannel.getLocalAddress(), java.net.DatagramSocket.getLocalAddress and java.net.DatagramSocket.getLocalSocketAddress methods

Specification

The apidoc for java.net.DatagramSocket.getLocalSocketAddress is changed as follows:

      /**
       * Returns the address of the endpoint this socket is bound to.
+      * <p>If the socket was initially bound to the wildcard address and
+      * is now {@link #isConnected connected}, then the address returned
+      * may be the local address selected as the source address for
+      * datagrams sent on this socket instead of the wildcard address.
+      * When {@link #disconnect()} is called, the bound address reverts
+      * to the wildcard address.
       *
       * @return a {@code SocketAddress} representing the local endpoint of this
       *         socket, or {@code null} if it is closed or not bound yet.

The apidoc for java.net.DatagramSocket.getLocalAddress is changed as follows:

      /**
       * Gets the local address to which the socket is bound.
+      * <p>If the socket was initially bound to the wildcard address and
+      * is now {@link #isConnected connected}, then the address returned
+      * may be the local address selected as the source address for
+      * datagrams sent on the socket instead of the wildcard address.
+      * When {@link #disconnect()} is called, the bound address reverts
+      * to the wildcard address.
       *
       * <p>If there is a security manager, its
       * {@code checkConnect} method is first called
       * with the host address and {@code -1}
       * as its arguments to see if the operation is allowed.

The apidoc for java.nio.channels.DatagramChannel.getLocalAddress is changed as follows:

      /**
       * {@inheritDoc}
       * <p>
+      * If the channel's socket was initially bound to the wildcard address and
+      * is now {@link #isConnected connected}, then the address returned
+      * may be the local address selected as the source address for
+      * datagrams sent via this channel instead of the wildcard address.
+      * When {@link #disconnect} is called, the bound address reverts
+      * to the wildcard address.
+      * <p>
       * If there is a security manager set, its {@code checkConnect} method is
       * called with the local address and {@code -1} as its arguments to see
       * if the operation is allowed. If the operation is not allowed,
       * a {@code SocketAddress} representing the
       * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
       * local port of the channel's socket is returned.
       *
       * @return  The {@code SocketAddress} that the socket is bound to, or the
       *          {@code SocketAddress} representing the loopback address if
       *          denied by the security manager, or {@code null} if the
-      *          channel's socket is not bound
+      *          channel's socket is not bound.
       *
       * @throws  ClosedChannelException     {@inheritDoc}
       * @throws  IOException                {@inheritDoc}
       */