6328537: Improve javadocs for Socket class by adding references to SocketOptions
Summary: Insert references to SocketOptions.java where applicable
Reviewed-by: alanb, chegar
--- a/jdk/src/share/classes/java/net/ServerSocket.java Tue May 14 22:36:52 2013 +0530
+++ b/jdk/src/share/classes/java/net/ServerSocket.java Tue May 14 12:01:38 2013 -0700
@@ -607,9 +607,9 @@
}
/**
- * Enable/disable SO_TIMEOUT with the specified timeout, in
- * milliseconds. With this option set to a non-zero timeout,
- * a call to accept() for this ServerSocket
+ * 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
@@ -629,9 +629,9 @@
}
/**
- * Retrieve setting for SO_TIMEOUT. 0 returns implies that the
- * option is disabled (i.e., timeout of infinity).
- * @return the SO_TIMEOUT value
+ * Retrieve setting for {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT}.
+ * 0 returns implies that the option is disabled (i.e., timeout of infinity).
+ * @return the {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT} value
* @exception IOException if an I/O error occurs
* @since JDK1.1
* @see #setSoTimeout(int)
@@ -649,7 +649,8 @@
}
/**
- * Enable/disable the SO_REUSEADDR socket option.
+ * Enable/disable the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}
+ * socket option.
* <p>
* When a TCP connection is closed the connection may remain
* in a timeout state for a period of time after the connection
@@ -660,24 +661,23 @@
* <tt>SocketAddress</tt> if there is a connection in the
* timeout state involving the socket address or port.
* <p>
- * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket
- * using {@link #bind(SocketAddress)} allows the socket to be
- * bound even though a previous connection is in a timeout
- * state.
+ * Enabling {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} prior to
+ * binding the socket using {@link #bind(SocketAddress)} allows the socket
+ * to be bound even though a previous connection is in a timeout state.
* <p>
* When a <tt>ServerSocket</tt> is created the initial setting
- * of <tt>SO_REUSEADDR</tt> is not defined. Applications can
- * use {@link #getReuseAddress()} to determine the initial
- * setting of <tt>SO_REUSEADDR</tt>.
+ * of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is not defined.
+ * Applications can use {@link #getReuseAddress()} to determine the initial
+ * setting of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}.
* <p>
- * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or
- * disabled after a socket is bound (See {@link #isBound()})
+ * The behaviour when {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is
+ * enabled or disabled after a socket is bound (See {@link #isBound()})
* is not defined.
*
* @param on whether to enable or disable the socket option
* @exception SocketException if an error occurs enabling or
- * disabling the <tt>SO_RESUEADDR</tt> socket option,
- * or the socket is closed.
+ * disabling the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}
+ * socket option, or the socket is closed.
* @since 1.4
* @see #getReuseAddress()
* @see #bind(SocketAddress)
@@ -691,9 +691,10 @@
}
/**
- * Tests if SO_REUSEADDR is enabled.
+ * Tests if {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled.
*
- * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is enabled.
+ * @return a <code>boolean</code> indicating whether or not
+ * {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since 1.4
@@ -768,15 +769,16 @@
}
/**
- * Sets a default proposed value for the SO_RCVBUF option for sockets
+ * Sets a default proposed value for the
+ * {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option for sockets
* accepted from this <tt>ServerSocket</tt>. The value actually set
* in the accepted socket must be determined by calling
* {@link Socket#getReceiveBufferSize()} after the socket
* is returned by {@link #accept()}.
* <p>
- * The value of SO_RCVBUF is used both to set the size of the internal
- * socket receive buffer, and to set the size of the TCP receive window
- * that is advertized to the remote peer.
+ * The value of {@link SocketOptions#SO_RCVBUF SO_RCVBUF} is used both to
+ * set the size of the internal socket receive buffer, and to set the size
+ * of the TCP receive window that is advertized to the remote peer.
* <p>
* It is possible to change the value subsequently, by calling
* {@link Socket#setReceiveBufferSize(int)}. However, if the application
@@ -812,15 +814,16 @@
}
/**
- * Gets the value of the SO_RCVBUF option for this <tt>ServerSocket</tt>,
- * that is the proposed buffer size that will be used for Sockets accepted
- * from this <tt>ServerSocket</tt>.
+ * Gets the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option
+ * for this <tt>ServerSocket</tt>, that is the proposed buffer size that
+ * will be used for Sockets accepted from this <tt>ServerSocket</tt>.
*
* <p>Note, the value actually set in the accepted socket is determined by
* calling {@link Socket#getReceiveBufferSize()}.
- * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>.
+ * @return the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF}
+ * option for this <tt>Socket</tt>.
* @exception SocketException if there is an error
- * in the underlying protocol, such as a TCP error.
+ * in the underlying protocol, such as a TCP error.
* @see #setReceiveBufferSize(int)
* @since 1.4
*/
--- a/jdk/src/share/classes/java/net/Socket.java Tue May 14 22:36:52 2013 +0530
+++ b/jdk/src/share/classes/java/net/Socket.java Tue May 14 12:01:38 2013 -0700
@@ -924,7 +924,8 @@
}
/**
- * Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).
+ * Enable/disable {@link SocketOptions#TCP_NODELAY TCP_NODELAY}
+ * (disable/enable Nagle's algorithm).
*
* @param on <code>true</code> to enable TCP_NODELAY,
* <code>false</code> to disable.
@@ -943,9 +944,10 @@
}
/**
- * Tests if TCP_NODELAY is enabled.
+ * Tests if {@link SocketOptions#TCP_NODELAY TCP_NODELAY} is enabled.
*
- * @return a <code>boolean</code> indicating whether or not TCP_NODELAY is enabled.
+ * @return a <code>boolean</code> indicating whether or not
+ * {@link SocketOptions#TCP_NODELAY TCP_NODELAY} is enabled.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since JDK1.1
@@ -958,8 +960,9 @@
}
/**
- * Enable/disable SO_LINGER with the specified linger time in seconds.
- * The maximum timeout value is platform specific.
+ * Enable/disable {@link SocketOptions#SO_LINGER SO_LINGER} with the
+ * specified linger time in seconds. The maximum timeout value is platform
+ * specific.
*
* The setting only affects socket close.
*
@@ -987,12 +990,13 @@
}
/**
- * Returns setting for SO_LINGER. -1 returns implies that the
+ * Returns setting for {@link SocketOptions#SO_LINGER SO_LINGER}.
+ * -1 returns implies that the
* option is disabled.
*
* The setting only affects socket close.
*
- * @return the setting for SO_LINGER.
+ * @return the setting for {@link SocketOptions#SO_LINGER SO_LINGER}.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since JDK1.1
@@ -1027,7 +1031,8 @@
}
/**
- * Enable/disable OOBINLINE (receipt of TCP urgent data)
+ * Enable/disable {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE}
+ * (receipt of TCP urgent data)
*
* By default, this option is disabled and TCP urgent data received on a
* socket is silently discarded. If the user wishes to receive urgent data, then
@@ -1039,8 +1044,9 @@
* and there is no capability to distinguish between normal data and urgent
* data unless provided by a higher level protocol.
*
- * @param on <code>true</code> to enable OOBINLINE,
- * <code>false</code> to disable.
+ * @param on <code>true</code> to enable
+ * {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE},
+ * <code>false</code> to disable.
*
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
@@ -1056,9 +1062,11 @@
}
/**
- * Tests if OOBINLINE is enabled.
+ * Tests if {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE} is enabled.
*
- * @return a <code>boolean</code> indicating whether or not OOBINLINE is enabled.
+ * @return a <code>boolean</code> indicating whether or not
+ * {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE}is enabled.
+ *
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since 1.4
@@ -1071,15 +1079,16 @@
}
/**
- * Enable/disable 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
+ * 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 > 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.
@@ -1096,11 +1105,13 @@
}
/**
- * Returns setting for SO_TIMEOUT. 0 returns implies that the
- * option is disabled (i.e., timeout of infinity).
- * @return the setting for SO_TIMEOUT
+ * Returns setting for {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT}.
+ * 0 returns implies that the option is disabled (i.e., timeout of infinity).
+ *
+ * @return the setting for {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT}
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
+ *
* @since JDK1.1
* @see #setSoTimeout(int)
*/
@@ -1117,14 +1128,15 @@
}
/**
- * Sets the SO_SNDBUF option to the specified value for this
- * <tt>Socket</tt>. The SO_SNDBUF option is used by the platform's
- * networking code as a hint for the size to set
- * the underlying network I/O buffers.
+ * Sets the {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option to the
+ * specified value for this <tt>Socket</tt>.
+ * The {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option is used by the
+ * platform's networking code as a hint for the size to set the underlying
+ * network I/O buffers.
*
- * <p>Because SO_SNDBUF is a hint, applications that want to
- * verify what size the buffers were set to should call
- * {@link #getSendBufferSize()}.
+ * <p>Because {@link SocketOptions#SO_SNDBUF SO_SNDBUF} is a hint,
+ * applications that want to verify what size the buffers were set to
+ * should call {@link #getSendBufferSize()}.
*
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
@@ -1149,10 +1161,11 @@
}
/**
- * Get value of the SO_SNDBUF option for this <tt>Socket</tt>,
- * that is the buffer size used by the platform
+ * Get value of the {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option
+ * for this <tt>Socket</tt>, that is the buffer size used by the platform
* for output on this <tt>Socket</tt>.
- * @return the value of the SO_SNDBUF option for this <tt>Socket</tt>.
+ * @return the value of the {@link SocketOptions#SO_SNDBUF SO_SNDBUF}
+ * option for this <tt>Socket</tt>.
*
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
@@ -1172,25 +1185,26 @@
}
/**
- * Sets the SO_RCVBUF option to the specified value for this
- * <tt>Socket</tt>. The SO_RCVBUF option is used by the platform's
- * networking code as a hint for the size to set
+ * Sets the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option to the
+ * specified value for this <tt>Socket</tt>. The
+ * {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option is
+ * used by the platform's networking code as a hint for the size to set
* the underlying network I/O buffers.
*
* <p>Increasing the receive buffer size can increase the performance of
* network I/O for high-volume connection, while decreasing it can
* help reduce the backlog of incoming data.
*
- * <p>Because SO_RCVBUF is a hint, applications that want to
- * verify what size the buffers were set to should call
- * {@link #getReceiveBufferSize()}.
+ * <p>Because {@link SocketOptions#SO_RCVBUF SO_RCVBUF} is a hint,
+ * applications that want to verify what size the buffers were set to
+ * should call {@link #getReceiveBufferSize()}.
*
- * <p>The value of SO_RCVBUF is also used to set the TCP receive window
- * that is advertized to the remote peer. Generally, the window size
- * can be modified at any time when a socket is connected. However, if
- * a receive window larger than 64K is required then this must be requested
- * <B>before</B> the socket is connected to the remote peer. There are two
- * cases to be aware of:<p>
+ * <p>The value of {@link SocketOptions#SO_RCVBUF SO_RCVBUF} is also used
+ * to set the TCP receive window that is advertized to the remote peer.
+ * Generally, the window size can be modified at any time when a socket is
+ * connected. However, if a receive window larger than 64K is required then
+ * this must be requested <B>before</B> the socket is connected to the
+ * remote peer. There are two cases to be aware of:<p>
* <ol>
* <li>For sockets accepted from a ServerSocket, this must be done by calling
* {@link ServerSocket#setReceiveBufferSize(int)} before the ServerSocket
@@ -1221,11 +1235,12 @@
}
/**
- * Gets the value of the SO_RCVBUF option for this <tt>Socket</tt>,
- * that is the buffer size used by the platform for
- * input on this <tt>Socket</tt>.
+ * Gets the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option
+ * for this <tt>Socket</tt>, that is the buffer size used by the platform
+ * for input on this <tt>Socket</tt>.
*
- * @return the value of the SO_RCVBUF option for this <tt>Socket</tt>.
+ * @return the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF}
+ * option for this <tt>Socket</tt>.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @see #setReceiveBufferSize(int)
@@ -1244,9 +1259,9 @@
}
/**
- * Enable/disable SO_KEEPALIVE.
+ * Enable/disable {@link SocketOptions#SO_KEEPALIVE SO_KEEPALIVE}.
*
- * @param on whether or not to have socket keep alive turned on.
+ * @param on whether or not to have socket keep alive turned on.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since 1.3
@@ -1259,9 +1274,10 @@
}
/**
- * Tests if SO_KEEPALIVE is enabled.
+ * Tests if {@link SocketOptions#SO_KEEPALIVE SO_KEEPALIVE} is enabled.
*
- * @return a <code>boolean</code> indicating whether or not SO_KEEPALIVE is enabled.
+ * @return a <code>boolean</code> indicating whether or not
+ * {@link SocketOptions#SO_KEEPALIVE SO_KEEPALIVE} is enabled.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since 1.3
@@ -1317,6 +1333,7 @@
* traffic class or type-of-service
* @since 1.4
* @see #getTrafficClass
+ * @see SocketOptions#IP_TOS
*/
public void setTrafficClass(int tc) throws SocketException {
if (tc < 0 || tc > 255)
@@ -1341,13 +1358,15 @@
* traffic class or type-of-service value.
* @since 1.4
* @see #setTrafficClass(int)
+ * @see SocketOptions#IP_TOS
*/
public int getTrafficClass() throws SocketException {
return ((Integer) (getImpl().getOption(SocketOptions.IP_TOS))).intValue();
}
/**
- * Enable/disable the SO_REUSEADDR socket option.
+ * Enable/disable the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}
+ * socket option.
* <p>
* When a TCP connection is closed the connection may remain
* in a timeout state for a period of time after the connection
@@ -1358,22 +1377,22 @@
* <tt>SocketAddress</tt> if there is a connection in the
* timeout state involving the socket address or port.
* <p>
- * Enabling <tt>SO_REUSEADDR</tt> prior to binding the socket
- * using {@link #bind(SocketAddress)} allows the socket to be
- * bound even though a previous connection is in a timeout
+ * Enabling {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}
+ * prior to binding the socket using {@link #bind(SocketAddress)} allows
+ * the socket to be bound even though a previous connection is in a timeout
* state.
* <p>
* When a <tt>Socket</tt> is created the initial setting
- * of <tt>SO_REUSEADDR</tt> is disabled.
+ * of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is disabled.
* <p>
- * The behaviour when <tt>SO_REUSEADDR</tt> is enabled or
- * disabled after a socket is bound (See {@link #isBound()})
+ * The behaviour when {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is
+ * enabled or disabled after a socket is bound (See {@link #isBound()})
* is not defined.
*
* @param on whether to enable or disable the socket option
* @exception SocketException if an error occurs enabling or
- * disabling the <tt>SO_RESUEADDR</tt> socket option,
- * or the socket is closed.
+ * disabling the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}
+ * socket option, or the socket is closed.
* @since 1.4
* @see #getReuseAddress()
* @see #bind(SocketAddress)
@@ -1387,9 +1406,10 @@
}
/**
- * Tests if SO_REUSEADDR is enabled.
+ * Tests if {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled.
*
- * @return a <code>boolean</code> indicating whether or not SO_REUSEADDR is enabled.
+ * @return a <code>boolean</code> indicating whether or not
+ * {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @since 1.4