增加一些注释

Author: likongpeng

src/main/java/java/net/ServerSocket.java

@@ -32,9 +32,11 @@
 import java.security.PrivilegedExceptionAction;
 
 /**
- * This class implements server sockets. A server socket waits for
- * requests to come in over the network. It performs some operation
- * based on that request, and then possibly returns a result to the requester.
+ *
+ * 等待客户端的套接字发送信息过来，并在处理完成之后，把响应回传给客户端
+  This class implements server sockets. A server socket waits for
+  requests to come in over the network. It performs some operation
+  based on that request, and then possibly returns a result to the requester.
  * <p>
  * The actual work of the server socket is performed by an instance
  * of the {@code SocketImpl} class. An application can
@@ -53,14 +55,12 @@ class ServerSocket implements java.io.Closeable {
     /**
      * Various states of this socket.
      */
-    private boolean created = false;
-    private boolean bound = false;
-    private boolean closed = false;
+    private boolean created = false;// 已创建
+    private boolean bound = false;// 绑定
+    private boolean closed = false;// 已关闭
     private Object closeLock = new Object();
 
-    /**
-     * The implementation of this Socket.
-     */
+    // 底层的功能都依靠 SocketImpl 来实现
     private SocketImpl impl;
 
     /**
@@ -131,15 +131,17 @@ public ServerSocket(int port) throws IOException {
     /**
      * Creates a server socket and binds it to the specified local port
      * number, with the specified backlog.
+     * 如果 port 是 0 的话，表示 port 是自动分配
      * A port number of {@code 0} means that the port number is
      * automatically allocated, typically from an ephemeral port range.
      * This port number can then be retrieved by calling
-     * {@link #getLocalPort getLocalPort}.
+      {@link #getLocalPort getLocalPort}.
      * <p>
-     * The maximum queue length for incoming connection indications (a
-     * request to connect) is set to the {@code backlog} parameter. If
-     * a connection indication arrives when the queue is full, the
-     * connection is refused.
+     *   最大的客户端连接数是由 backlog 来控制的，如果要作为构造器入参传入的话，应该是大于 0 的
+      The maximum queue length for incoming connection indications (a
+      request to connect) is set to the {@code backlog} parameter. If
+      a connection indication arrives when the queue is full, the
+      connection is refused.
      * <p>
      * If the application has specified a server socket factory, that
      * factory's {@code createSocketImpl} method is called to create
@@ -151,18 +153,18 @@ public ServerSocket(int port) throws IOException {
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
-     * The {@code backlog} 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}. If it is less than or equal to
-     * {@code 0}, then an implementation specific default will be used.
+      The {@code backlog} 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}. If it is less than or equal to
+      {@code 0}, then an implementation specific default will be used.
      * <P>
      *
      * @param      port     the port number, or {@code 0} to use a port
      *                      number that is automatically allocated.
      * @param      backlog  requested maximum length of the queue of incoming
-     *                      connections.
+                          connections.
      *
      * @exception  IOException  if an I/O error occurs when opening the socket.
      * @exception  SecurityException
@@ -227,13 +229,17 @@ public ServerSocket(int port, int backlog) throws IOException {
      * @since   JDK1.1
      */
     public ServerSocket(int port, int backlog, InetAddress bindAddr) throws IOException {
+        // 默认是 SocksSocketImpl 实现
         setImpl();
+        // 端口必须大于 0，小于 65535
         if (port < 0 || port > 0xFFFF)
             throw new IllegalArgumentException(
                        "Port value out of range: " + port);
+        // 最大可连接数如果小于1，那么采取默认的 50
         if (backlog < 1)
           backlog = 50;
         try {
+            // 底层 navtive 方法
             bind(new InetSocketAddress(bindAddr, port), backlog);
         } catch(SecurityException e) {
             close();
@@ -476,8 +482,9 @@ public SocketAddress getLocalSocketAddress() {
     }
 
     /**
-     * Listens for a connection to be made to this socket and accepts
-     * it. The method blocks until a connection is made.
+     *
+      Listens for a connection to be made to this socket and accepts
+      it. The method blocks until a connection is made.
      *
      * <p>A new Socket {@code s} is created and, if there
      * is a security manager,

src/main/java/java/net/Socket.java

@@ -52,21 +52,17 @@
  */
 public
 class Socket implements java.io.Closeable {
-    /**
-     * Various states of this socket.
-     */
+
+
     // 套接字的状态
     private boolean created = false;// 已创建
     private boolean bound = false;// 已绑定
     private boolean connected = false;// 已连接
     private boolean closed = false;// 已关闭
-    private Object closeLock = new Object();
-    private boolean shutIn = false;
-    private boolean shutOut = false;
+    private Object closeLock = new Object();// 关闭锁
+    private boolean shutIn = false;// 读是否关闭
+    private boolean shutOut = false;// 写是否关闭
 
-    /**
-     * The implementation of this Socket.
-     */
     // 套接字的实现
     SocketImpl impl;
 
@@ -107,7 +103,7 @@ void setImpl() {
 
     /**
      * Creates an unconnected socket, specifying the type of proxy, if any,
-     * that should be used regardless of any other settings.
+      that should be used regardless of any other settings.
      * <P>
      * If there is a security manager, its {@code checkConnect} method
      * is called with the proxy host address and port number
@@ -552,7 +548,7 @@ public void connect(SocketAddress endpoint) throws IOException {
     /**
      * Connects this socket to the server with a specified timeout value.
      * A timeout of zero is interpreted as an infinite timeout. The connection
-     * will then block until established or an error occurs.
+     will then block until established or an error occurs.
      *
      * @param   endpoint the {@code SocketAddress}
      * @param   timeout  the timeout value to be used in milliseconds.
@@ -1026,11 +1022,17 @@ public boolean getTcpNoDelay() throws SocketException {
      * @since JDK1.1
      * @see #getSoLinger()
      */
+    // on 为 false，表示不启用延时关闭，true 的话表示启用延时关闭
+    // linger 为延时的时间，单位秒
     public void setSoLinger(boolean on, int linger) throws SocketException {
+        // 检查是否已经关闭
         if (isClosed())
             throw new SocketException("Socket is closed");
+        // 不启用延时关闭
         if (!on) {
             getImpl().setOption(SocketOptions.SO_LINGER, new Boolean(on));
+        // 启用延时关闭，如果 linger 为 0，那么会立即关闭
+        // linger 最大为 65535 秒，约 18 小时
         } else {
             if (linger < 0) {
                 throw new IllegalArgumentException("invalid value for SO_LINGER");
@@ -1086,15 +1088,18 @@ public void sendUrgentData (int data) throws IOException  {
      * 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
-     * this option must be enabled. When enabled, urgent data is received
-     * inline with normal data.
+     * 默认情况下，该选项被禁用，表示接收到 TCP urgent data 时，数据将被默默丢弃
+     * By default, this option is disabled and TCP urgent data received on a socket is silently discarded.
+     * 如果希望接受 urgent data 数据，该选项必须开启
+      If the user wishes to receive urgent data, then this option must be enabled.
+      When enabled, urgent data is received inline with normal data.
      * <p>
-     * Note, only limited support is provided for handling incoming urgent
-     * data. In particular, no notification of incoming urgent data is provided
-     * and there is no capability to distinguish between normal data and urgent
-     * data unless provided by a higher level protocol.
+     * 只提供有限的功能来处理紧急数据
+     * Note, only limited support is provided for handling incoming urgent data.
+     * 一般是不提供紧急数据的通知的，除非有更高级协议的支持
+     * In particular, no notification of incoming urgent data is provided
+      and there is no capability to distinguish between normal data and urgent
+      data unless provided by a higher level protocol.
      *
      * @param on {@code true} to enable
      *           {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE},
@@ -1139,6 +1144,7 @@ public boolean getOOBInline() throws SocketException {
      *  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}.
+     *  设置 0 的话，就是无限超时的意思
      *  A timeout of zero is interpreted as an infinite timeout.
      *
      * @param timeout the specified timeout, in milliseconds.
@@ -1183,18 +1189,18 @@ public synchronized int getSoTimeout() throws SocketException {
      * Sets the {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option to the
      * specified value for this {@code Socket}.
      * 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.
+      platform's networking code as a hint for the size to set the underlying
+      network I/O buffers.
      *
      * <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()}.
+      should call {@link #getSendBufferSize()}.
      *
      * @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.
      *
      * @param size the size to which to set the send buffer
-     * size. This value must be greater than 0.
+      size. This value must be greater than 0.
      *
      * @exception IllegalArgumentException if the
      * value is 0 or is negative.
@@ -1239,30 +1245,38 @@ public synchronized int getSendBufferSize() throws SocketException {
     /**
      * Sets the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option to the
      * specified value for this {@code Socket}. 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.
+      {@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.
+     * 增加接受缓冲值可以提高大数据量传递时的 IO 的性能，减少时，可以帮助减少数据的积压
+     * 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 {@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 {@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:
+      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.
+     然而，当窗口大小大于 64k 时，需要注意：
+     1：必须在 Socket 连接客户端之前设置缓冲值
+     2：必须在 ServerSocket 绑定本地地址之前设置缓冲值
+      However, if a receive window larger than 64K is required then
+      this must be requested before the socket is connected to the
+      remote peer. There are two cases to be aware of:
      * <ol>
      * <li>For sockets accepted from a ServerSocket, this must be done by calling
-     * {@link ServerSocket#setReceiveBufferSize(int)} before the ServerSocket
-     * is bound to a local address.<p></li>
-     * <li>For client sockets, setReceiveBufferSize() must be called before
-     * connecting the socket to its remote peer.</li></ol>
+       before the ServerSocket is bound to a local address.
+     <p></li>
+     * <li>
+     *   For client sockets, setReceiveBufferSize() must be called before
+      connecting the socket to its remote peer.
+     </li></ol>
      * @param size the size to which to set the receive buffer
      * size. This value must be greater than 0.
      *
@@ -1420,19 +1434,21 @@ public int getTrafficClass() throws SocketException {
      * 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
-     * is closed (typically known as the {@code TIME_WAIT} state
-     * or {@code 2MSL} wait state).
-     * For applications using a well known socket address or port
-     * it may not be possible to bind a socket to the required
-     * {@code SocketAddress} if there is a connection in the
-     * timeout state involving the socket address or port.
+        套接字在关闭之后，可能会等待一段时间之后才会真正的关闭，如果此时有新的套接字前来绑定同样的地址和端口时，
+        如果 setReuseAddress 为 true 的话，就可以绑定成功，否则绑定失败
+      When a TCP connection is closed the connection may remain
+      in a timeout state for a period of time after the connection
+      is closed (typically known as the {@code TIME_WAIT} state
+      or {@code 2MSL} wait state).
+      For applications using a well known socket address or port
+      it may not be possible to bind a socket to the required
+      {@code SocketAddress} if there is a connection in the
+      timeout state involving the socket address or port.
      * <p>
-     * 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.
+     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 {@code Socket} is created the initial setting
      * of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is disabled.