Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8232166

Correct contradictions in timeout range descriptions

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 14
    • core-libs
    • minimal
    • This is a doc only fix.
    • Java API
    • SE

    Description

      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 {

      Attachments

        Issue Links

          Activity

            People

              pconcannon Patrick Concannon (Inactive)
              darcy Joe Darcy
              Chris Hegarty, Daniel Fuchs
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: