Summary
-------

Update the default implementation of the new-style socket options
methods of `java.net.SocketImpl` and `java.net.DatagramSocketImpl`. As
well as the throwing specification and behaviour of the new-style
socket option methods of the four `java.net` socket types.

Problem
-------

The `java.net` TCP-based socket types, `ServerSocket` and `Socket`, have
their implementations backed by `java.net.SocketImpl`. The `java.net`
UDP-based socket types, `DatagramSocket` and `MulticastSocket`, have
their implementations backed by `java.net.DatagramSocketImpl`. The
backing socket _impl_ allows for different implementations to be plugged
into the socket APIs, which amounts to an SPI-like mechanism ( dating
back to the Java 1.0 era ).

When the three new-style methods for socket options, namely `getOption`,
`setOption`, and `supportedOptions`, were added in Java 9, to the four
`java.net` socket types, the supporting `SocketImpl` and
`DatagramSocketImpl` were also retrofitted with similar methods. Since
`SocketImpl` and `DatagramSocketImpl` are abstract classes, a default
implementation of these three new methods was added ( to allow backward
compatibility with pre-existing implementations ).

The default implementation of `SocketImpl::supportedOptions` returns a
set of socket options that represent that of what a typical
`ServerSocket` implementation may choose to support. The default
implementation of `SocketImpl::getOption` and `SocketImpl::setOption`
do some basic forwarding of the new-style options to the old-style
options, otherwise throw (the specified) `UnsupportedOperationException`, indicating that the `SocketImpl` does not support the option. Given
that the default `supportedOptions` support only the small set of
three server-like socket options ( `SO_RCVBUF`, `SO_REUSEADDR`, and
`IP_TOS`), the `getOption`/`setOption` methods only forward these three
socket options. This default implementation is neither specified nor
documented.

Similarly, the default implementation of
`DatagramSocketImpl::supportedOptions` returns a set of socket options
that represent that of what a typical `DatagramSocket` implementation
may choose to support. The default implementation of
`DatagramSocketImpl::getOption` and `DatagramSocketImpl::setOption` do
some basic forwarding of the new-style options to the old-style options,
otherwise throw (the specified) `UnsupportedOperationException` -
indicating that the `DatagramSocketImpl` does not support the option.
Given that the default `supportedOptions` support only the small set
of socket options ( `SO_SNDBUF`,  `SO_RCVBUF`, `SO_REUSEADDR`, and
`IP_TOS`), the `getOption`/`setOption` methods only forward these four
socket options. This default implementation is neither specified nor
documented.

Given the above limited default implementations, it is reasonable to
assume that any concrete implementation of `SocketImpl` or
`DatagramSocketImpl`, will have to override these three new-style socket
option methods, to provide their own implementation tailored to the
specific socket options that they support. With that in mind, it would
be simpler and more straight forward to reduce the default
implementation and add a note suggesting that subclasses provide their
own implementation. Additionally, in some cases an effective non-empty
( no-op ) specification-compliant default implementation is not
practicable, e.g. it is not possible to for `getOption` to throw an
`IOExcepton` after the socket impl is closed, since the socket impl has
no specified state. 

---

The second part of this CSR is concerted with the behavioural ( and
minor specification ) aspects of the exceptions thrown when "bad" values
are given to the following methods:

    Socket::setOption(SocketOption name, T value)
    Socket::getOption(SocketOption name)
    ServerSocket::setOption(SocketOption name, T value)
    ServerSocket::getOption(SocketOption name)
    DatagramSocket::setOption(SocketOption name, T value)
    DatagramSocket::getOption(SocketOption name)
    MulticastSocket::setOption(SocketOption name, T value)
    MulticastSocket::getOption(SocketOption name)
    SocketImpl::setOption(SocketOption name, T value)
    SocketImpl::getOption(SocketOption name)
    DatagramSocketImpl::setOption(SocketOption name, T value)
    DatagramSocketImpl::getOption(SocketOption name)

The aforementioned methods are specified to throw:

  1) `NullPointerException` if given a `null` socket option `name`
   ( they currently may throw `UnsupportedOperationException` )

  2) `IllegalArgumentException` if given a "bad" socket option `value`
   ( they currently may throw `SocketException` )

  3) `IOException` if invoked after the socket has been closed
   ( they currently continue to operate, or may throw `SocketException`)

Additionally, there are some inconsistencies in their respective
specifications across socket and impl types, when it comes to the
documentation of particular exceptions, e.g. `SocketImpl::setValue` is
missing an `@throws IllegalArgumentException`, while `Socket::setValue`
documents it ( `Socket::setValue` cannot actually validate the option
value, validation is performed by the impl ).
`DatagramSocketImpl::setValue` has a similar issue. Also, there are some
`@throws NullPointerException` missing.


Solution
--------

  1) Update ( simplify ) and specify the default implementation of the
     three new-style socket option methods of `SocketImpl` and
     `DatagramSocketImpl`. More specifically, change the default
     implementation of `supportedOptions` to return an empty set -
     indicating that no socket options are supported. The default
     implementation of `getOption`/`setOption` can then be updated to
     always throw `UnsupportedOperationException`, as logically no
     socket options are supported.

  2) Update the implementation of the four `java.net` socket types, and
     the two impl types, to match their specification. That is, to
     throw the specified exception when "bad" input is given.

  3) Make the specification of all three new-style socket option
     methods consistent, with respect to their specified exceptions,
     across all four socket types and two socket impls.

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

`java.net.SocketImpl`

       /**
        * Returns a set of SocketOptions supported by this impl
        * and by this impl's socket (Socket or ServerSocket)
        *
    +   * @implSpec
    +   * The default implementation of this method returns an empty set.
    +   * Subclasses should override this method with an appropriate implementation.
    +   *
        * @return a Set of SocketOptions
        *
        * @since 9
        */
       protected Set<SocketOption<?>> supportedOptions()

       /**
        * Called to set a socket option.
        *
    +   * @implSpec
    +   * The default implementation of this method first checks that the given
    +   * socket option {code name} is not null, then throws {@code
    +   * UnsupportedOperationException}. Subclasses should override this method
    +   * with an appropriate implementation.
    +   *
        * @param <T> The type of the socket option value
        * @param name The socket option
        * @param value The value of the socket option. A value of {@code null}
        *              may be valid for some options.
        *
        * @throws UnsupportedOperationException if the SocketImpl does not
        *         support the option
    +   * @throws IllegalArgumentException if the value is not valid for
    +   *         the option
        * @throws IOException if an I/O error occurs, or if the socket is closed
    +   * @throws NullPointerException if name is {@code null}
        *
        * @since 9
        */
       protected <T> void setOption(SocketOption<T> name, T value) throws IOException

       /**
        * Called to get a socket option.
        *
    +   * @implSpec
    +   * The default implementation of this method first checks that the given
    +   * socket option {code name} is not null, then throws {@code
    +   * UnsupportedOperationException}. Subclasses should override this method
    +   * with an appropriate implementation.
    +   *
        * @param <T> The type of the socket option value
        * @param name The socket option
        * @return the value of the named option
        *
        * @throws UnsupportedOperationException if the SocketImpl does not
        *         support the option
        * @throws IOException if an I/O error occurs, or if the socket is closed
    +   * @throws NullPointerException if name is {@code null}
        *
        * @since 9
        */
        protected <T> T getOption(SocketOption<T> name) throws IOException


`java.net.DatagramSocketImpl`

       /**
        * Returns a set of SocketOptions supported by this impl
        * and by this impl's socket (DatagramSocket or MulticastSocket)
        *
    +   * @implSpec
    +   * The default implementation of this method returns an empty set.
    +   * Subclasses should override this method with an appropriate implementation.
    +   *
        * @return a Set of SocketOptions
        *
        * @since 9
        */
       protected Set<SocketOption<?>> supportedOptions()

       /**
        * Called to set a socket option.
        *
    +   * @implSpec
    +   * The default implementation of this method first checks that the given
    +   * socket option {code name} is not null, then throws {@code
    +   * UnsupportedOperationException}. Subclasses should override this method
    +   * with an appropriate implementation.
    +   *
        * @param <T> The type of the socket option value
        * @param name The socket option
        * @param value The value of the socket option. A value of {@code null}
        *              may be valid for some options.
        *
        * @throws UnsupportedOperationException if the DatagramSocketImpl does not
        *         support the option
    +   * @throws IllegalArgumentException if the value is not valid for
    +   *         the option
    -   * @throws IOException if an I/O problem occurs while attempting to set the option
    +   * @throws IOException if an I/O error occurs, or if the socket is closed
        * @throws NullPointerException if name is {@code null}
        *
        * @since 9
        */
       protected <T> void setOption(SocketOption<T> name, T value) throws IOException

       /**
        * Called to get a socket option.
        *
    +   * @implSpec
    +   * The default implementation of this method first checks that the given
    +   * socket option {code name} is not null, then throws {@code
    +   * UnsupportedOperationException}. Subclasses should override this method
    +   * with an appropriate implementation.
    +   *
        * @param <T> The type of the socket option value
        * @param name The socket option
        * @return the socket option
        *
        * @throws UnsupportedOperationException if the DatagramSocketImpl does not
        *         support the option
    -   * @throws IOException if an I/O problem occurs while attempting to set the option
    +   * @throws IOException if an I/O error occurs, or if the socket is closed
        * @throws NullPointerException if name is {@code null}
        *
        * @since 9
        */
       protected <T> T getOption(SocketOption<T> name) throws IOException