Summary
-------
It was observed that DatagramSocket.setSoTimeout, Socket.setSoTimeout and ServerSocket.setTimeout have a contradiction in their description of the valid range for a timeout value:
Problem
-------
The API documentation states:
"The timeout must be {@code > 0}. A timeout of zero is interpreted as an infinite timeout."
Solution
--------
Change the wording of the specification as shown below.
Specification
-------------
DatagramSocket::setSoTimeout
/** Enable/disable SO_TIMEOUT with the specified timeout, in
- * milliseconds. With this option set to a non-zero timeout,
+ * milliseconds. With this option set to a positive timeout value,
* a call to receive() for this DatagramSocket
* will block for only this amount of time. If the timeout expires,
* a <B>java.net.SocketTimeoutException</B> is raised, though the
- * DatagramSocket 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.
+ * DatagramSocket is still valid. A timeout of zero is interpreted
+ * as an infinite timeout.
+ * The option <B>must</B> be enabled prior to entering the blocking
+ * operation to have effect.
*
* @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 {
ServerSocket::setSoTimeout
/**
* 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
+ * specified timeout, in milliseconds. With this option set to a positive
+ * timeout value, 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.
+ * ServerSocket is still valid. A timeout of zero is interpreted as an
+ * infinite timeout.
+ * The option <B>must</B> be enabled prior to entering the blocking
+ * operation to have effect.
+ *
* @param timeout the specified timeout, in milliseconds
* @throws 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 {
Socket::setSoTimeout
/**
* 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
+ * to a positive timeout value, 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.
+ * Socket is still valid. A timeout of zero is interpreted as an infinite timeout.
+ * The option <B>must</B> be enabled prior to entering the blocking operation
+ * to have effect.
*
* @param timeout the specified timeout, in milliseconds.
* @throws 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 {