Summary

Clarifies the behaviour of the setSoTimeout() method when given a negative timeout value.

Problem

With this option set to a non-zero timeout, a call to receive() for this DatagramSocket will block for the specified time. Any value less than zero is invalid, and as such, should throw an IllegalArgumentException. However, setSoTimeout() does not specify what happens if given a negative timeout value.

Solution

The solution is to document that a negative timeout value will result in an IllegalArgumentException being thrown. As the setSoTimeout() method already throws an IllegalArgumentException, this change is effectively documenting existing long-standing behaviour.

However, an explicit check on negative values will now be made in the setSoTimeout() method to avoid dependence on implementation for such a check to occur.

Specification

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

      *
      * @param timeout the specified timeout in milliseconds.
      * @throws SocketException if there is an error in the underlying protocol, such as an UDP error.
+    * @throws IllegalArgumentException if {@code timeout} is negative
      * @since   1.1
      * @see #getSoTimeout()
      */
     public synchronized void setSoTimeout(int timeout) throws SocketException {... }

Webrev: http://cr.openjdk.java.net/~pconcannon/8222829/webrevs/webrev.02/