Summary
-------

Specify behaviour of the timeout accepting methods of `Socket` and
`ServerSocket`, when the given a negative timeout.

Problem
-------

The problem is that the specification of the following three methods
requires the given `timeout` argument to be non-negative, but does not
specify what happens if given a negative timeout value.

    ServerSocket.setSoTimeout(int timeout)
    Socket.seSoTimeout(int timeout)
    Socket.connect(SocketAddress address, int timeout)

Solution
--------

The solution is to document, in all three of the aforementioned methods,
that a negative `timeout` value will result in an
`IllegalArgumentException` being thrown.

The above methods already throw `IllegalArgumentException`, so this
change is effectively documenting existing long-standing behaviour.

Note: Before this change, `ServerSocket::setSoTimeout` defers the
timeout argument checking to its socket impl. The default plain socket
impl throws `IllegalArgumentException` if given a negative timeout. It
is possible, but unlikely, that an alternative custom socket impl could
have accepted a negative timeout, but the effects of such are
unspecified and unknown. After this change, ServerSocket will no longer
defer the timeout argument checking, it will check its own arguments.

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

src/java.base/share/classes/java/net/ServerSocket.java

     /**
      * Enable/disable {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT} with the
      * specified timeout, in milliseconds.  With this option set to a non-zero
      * timeout, a call to accept() for this ServerSocket
      * will block for only this amount of time.  If the timeout expires,
      * a <B>java.net.SocketTimeoutException</B> is raised, though the
      * ServerSocket is still valid.  The option <B>must</B> be enabled
      * prior to entering the blocking operation to have effect.  The
      * timeout must be {@code > 0}.
      * A timeout of zero is interpreted as an infinite timeout.
      * @param timeout the specified timeout, in milliseconds
      * @exception SocketException if there is an error in
      * the underlying protocol, such as a TCP error.
    + * @throws  IllegalArgumentException  if {@code timeout} is negative
      * @since   1.1
      * @see #getSoTimeout()
      */
     public synchronized void setSoTimeout(int timeout) throws SocketException


src/java.base/share/classes/java/net/Socket.java

     /**
      * Connects this socket to the server with a specified timeout value.
      * A timeout of zero is interpreted as an infinite timeout. The connection
      * will then block until established or an error occurs.
      *
      * @param   endpoint the {@code SocketAddress}
      * @param   timeout  the timeout value to be used in milliseconds.
      * @throws  IOException if an error occurs during the connection
      * @throws  SocketTimeoutException if timeout expires before connecting
      * @throws  java.nio.channels.IllegalBlockingModeException
      *          if this socket has an associated channel,
      *          and the channel is in non-blocking mode
      * @throws  IllegalArgumentException if endpoint is null or is a
    - *          SocketAddress subclass not supported by this socket
    + *          SocketAddress subclass not supported by this socket, or
    + *          if {@code timeout} is negative
      * @since 1.4
      * @spec JSR-51
      */
     public void connect(SocketAddress endpoint, int timeout) throws IOException

      /**
       *  Enable/disable {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT}
       *  with the specified timeout, in milliseconds. With this option set
       *  to a non-zero timeout, a read() call on the InputStream associated with
       *  this Socket will block for only this amount of time.  If the timeout
       *  expires, a <B>java.net.SocketTimeoutException</B> is raised, though the
       *  Socket is still valid. The option <B>must</B> be enabled
       *  prior to entering the blocking operation to have effect. The
       *  timeout must be {@code > 0}.
       *  A timeout of zero is interpreted as an infinite timeout.
       *
       * @param timeout the specified timeout, in milliseconds.
       * @exception SocketException if there is an error
       * in the underlying protocol, such as a TCP error.
     + * @throws  IllegalArgumentException if {@code timeout} is negative
       * @since   1.1
       * @see #getSoTimeout()
       */
      public synchronized void setSoTimeout(int timeout) throws SocketException