Summary
-------
`DatagramSocket`'s `connect` and `disconnect` methods do not throw an `IOException` while `DatagramChannel`'s corresponding methods do. The potential failure behaviour of the `DatagramSocket`'s methods should be clarified.

Problem
-------

The behaviour of `DatagramSocket` `connect` and `disconnect` methods when an IO error occurs is not clear.  For instance, the two-args `DatagramSocket::connect` method currently might throw an Error, which is undocumented behavior and not user-friendly.

Solution
--------

Update the specification of `DatagramSocket::connect` and `DatagramSocket::disconnect` to document that an implementation may throw `UncheckedIOException`. In addition, and similar to what was done for `DatagramChannel`, an @apiNote will be added to `DatagramSocket::disconnect` to recommend closing the socket if an IO exception occurs, as the underlying socket might have been left in an inconsistent and unspecified state. The two-args `DatagramSocket::connect` implementation used to throw an `Error` if a `SocketException` occurred (for instance, if the socket was not bound and the implicit bind failed). This is undocumented behavior, and this will now be changed to throw the documented `UncheckedIOException` instead. Similarly the `DatagramChannel` socket adapter used to throw an Error if connect (two-args) or disconnect failed, and will now be changed to throw `UncheckedIOException` instead, in conformance to the updated specification.

As it appears that the current omission of `throws IOException` from the declaration of these methods was likely an oversight - one that cannot be easily fixed now since it would be source incompatible - an UncheckedIOException is now being thrown.

Specification
-------------

DatagramSocket::connect

    /**
         * Connects the socket to a remote address for this socket. When a
         * socket is connected to a remote address, packets may only be
         * sent to or received from that address. By default a datagram
    -    * socket is not connected.
    +    * socket is not connected. If the socket is already closed,
    +    * then this method has no effect.
         *
    -    * <p>If the remote destination to which the socket is connected does not
    -    * exist, or is otherwise unreachable, and if an ICMP destination unreachable
    -    * packet has been received for that address, then a subsequent call to
    -    * send or receive may throw a PortUnreachableException. Note, there is no
    -    * guarantee that the exception will be thrown.
    +    * <p> If this socket is not bound then this method will first cause the
    +    * socket to be bound to an address that is assigned automatically,
    +    * as if invoking the {@link #bind bind} method with a parameter of
    +    * {@code null}. If the remote destination to which the socket is connected
    +    * does not exist, or is otherwise unreachable, and if an ICMP destination
    +    * unreachable packet has been received for that address, then a subsequent
    +    * call to send or receive may throw a PortUnreachableException. Note,
    +    * there is no guarantee that the exception will be thrown.
         *
         * ...
         *
         * @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 out of range.
         *
         * @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) {


          * 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.
    +     * <p> If given an {@link InetSocketAddress InetSocketAddress}, this method
    +     * behaves as if invoking {@link #connect(InetAddress,int) connect(InetAddress,int)},
    +     * except that {@code SocketException} that may be raised are not wrapped in
    +     * {@code UncheckedIOException}.   
    ...
    public void connect(SocketAddress addr) throws SocketException {

DatagramSocket::disconnect


         /**
          * Disconnects the socket. If the socket is closed or not connected,
          * then this method has no effect.
          *
    +     * @apiNote If this method throws an UncheckedIOException, the socket
    +     *          may be left in an unspecified state. It is strongly
    +     *          recommended that the socket be closed when disconnect
    +     *          fails.
    +     *
    +     * @throws  UncheckedIOException
    +     *          may be thrown if it fails to dissolve the
    +     *          association and restore the socket to a consistent state
    +     *
          * @see #connect
    +     * @since 1.2
          */
         public void disconnect() {