6258215: Num of backlog in ServerSocket(int, int) should be mentioned more explicitly

Summary: updated javadoc
Reviewed-by: chegar

2 files changed, 40 insertions, 22 deletions

diff --git a/src/share/classes/java/net/ServerSocket.java b/src/share/classes/java/net/ServerSocket.java
index d28d874b2..983c737c3 100644
--- a/src/share/classes/java/net/ServerSocket.java
+++ b/src/share/classes/java/net/ServerSocket.java
@@ -142,14 +142,18 @@ class ServerSocket implements java.io.Closeable {
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
-     * <P>The <code>backlog</code> argument must be a positive
-     * value greater than 0. If the value passed is equal or less
-     * than 0, then the default value will be assumed.
+     * The <code>backlog</code> argument is the requested maximum number of
+     * pending connections on the socket. Its exact semantics are implementation
+     * specific. In particular, an implementation may impose a maximum length
+     * or may choose to ignore the parameter altogther. The value provided
+     * should be greater than <code>0</code>. If it is less than or equal to
+     * <code>0</code>, then an implementation specific default will be used.
      * <P>
      *
      * @param      port     the port number, or <code>0</code> to use a port
      *                      number that is automatically allocated.
-     * @param      backlog  the maximum length of the queue.
+     * @param      backlog  requested maximum length of the queue of incoming
+     *                      connections.
      *
      * @exception  IOException  if an I/O error occurs when opening the socket.
      * @exception  SecurityException
@@ -187,13 +191,17 @@ class ServerSocket implements java.io.Closeable {
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
-     * <P>The <code>backlog</code> argument must be a positive
-     * value greater than 0. If the value passed is equal or less
-     * than 0, then the default value will be assumed.
+     * The <code>backlog</code> argument is the requested maximum number of
+     * pending connections on the socket. Its exact semantics are implementation
+     * specific. In particular, an implementation may impose a maximum length
+     * or may choose to ignore the parameter altogther. The value provided
+     * should be greater than <code>0</code>. If it is less than or equal to
+     * <code>0</code>, then an implementation specific default will be used.
      * <P>
      * @param port  the port number, or <code>0</code> to use a port
      *              number that is automatically allocated.
-     * @param backlog the listen backlog
+     * @param backlog requested maximum length of the queue of incoming
+     *                connections.
      * @param bindAddr the local InetAddress the server will bind to
      *
      * @throws  SecurityException if a security manager exists and
@@ -321,11 +329,15 @@ class ServerSocket implements java.io.Closeable {
      * If the address is <code>null</code>, then the system will pick up
      * an ephemeral port and a valid local address to bind the socket.
      * <P>
-     * The <code>backlog</code> argument must be a positive
-     * value greater than 0. If the value passed is equal or less
-     * than 0, then the default value will be assumed.
+     * The <code>backlog</code> argument is the requested maximum number of
+     * pending connections on the socket. Its exact semantics are implementation
+     * specific. In particular, an implementation may impose a maximum length
+     * or may choose to ignore the parameter altogther. The value provided
+     * should be greater than <code>0</code>. If it is less than or equal to
+     * <code>0</code>, then an implementation specific default will be used.
      * @param   endpoint        The IP address & port number to bind to.
-     * @param   backlog         The listen backlog length.
+     * @param   backlog         requested maximum length of the queue of
+     *                          incoming connections.
      * @throws  IOException if the bind operation fails, or if the socket
      *                     is already bound.
      * @throws  SecurityException       if a <code>SecurityManager</code> is present and
diff --git a/src/share/classes/javax/net/ssl/SSLServerSocket.java b/src/share/classes/javax/net/ssl/SSLServerSocket.java
index cdeef2baf..cafc72df8 100644
--- a/src/share/classes/javax/net/ssl/SSLServerSocket.java
+++ b/src/share/classes/javax/net/ssl/SSLServerSocket.java
@@ -108,9 +108,12 @@ public abstract class SSLServerSocket extends ServerSocket
      * <P>
      * A port number of <code>0</code> creates a socket on any free port.
      * <P>
-     * The <code>backlog</code> argument must be a positive
-     * value greater than 0. If the value passed if equal or less
-     * than 0, then the default value will be assumed.
+     * The <code>backlog</code> argument is the requested maximum number of
+     * pending connections on the socket. Its exact semantics are implementation
+     * specific. In particular, an implementation may impose a maximum length
+     * or may choose to ignore the parameter altogther. The value provided
+     * should be greater than <code>0</code>. If it is less than or equal to
+     * <code>0</code>, then an implementation specific default will be used.
      * <P>
      * If there is a security manager, its <code>checkListen</code>
      * method is called with the <code>port</code> argument as its
@@ -118,8 +121,8 @@ public abstract class SSLServerSocket extends ServerSocket
      * in a SecurityException.
      *
      * @param port the port on which to listen
-     * @param backlog how many connections may be pending before
-     *          the system should start rejecting new requests
+     * @param backlog  requested maximum length of the queue of incoming
+     *                  connections.
      * @throws IOException if an I/O error occurs when creating the socket
      * @throws SecurityException if a security manager exists and its
      *         <code>checkListen</code> method doesn't allow the operation.
@@ -150,16 +153,19 @@ public abstract class SSLServerSocket extends ServerSocket
      * <P>
      * A port number of <code>0</code> creates a socket on any free port.
      * <P>
-     * <P>The <code>backlog</code> argument must be a positive
-     * value greater than 0. If the value passed if equal or less
-     * than 0, then the default value will be assumed.
+     * The <code>backlog</code> argument is the requested maximum number of
+     * pending connections on the socket. Its exact semantics are implementation
+     * specific. In particular, an implementation may impose a maximum length
+     * or may choose to ignore the parameter altogther. The value provided
+     * should be greater than <code>0</code>. If it is less than or equal to
+     * <code>0</code>, then an implementation specific default will be used.
      * <P>
      * If <i>address</i> is null, it will default accepting connections
      * on any/all local addresses.
      *
      * @param port the port on which to listen
-     * @param backlog how many connections may be pending before
-     *          the system should start rejecting new requests
+     * @param backlog  requested maximum length of the queue of incoming
+     *                  connections.
      * @param address the address of the network interface through
      *          which connections will be accepted
      * @throws IOException if an I/O error occurs when creating the socket