harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772095 [4/6] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
Date Wed, 06 May 2009 08:33:22 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ServerSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ServerSocket.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ServerSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ServerSocket.java Wed May  6 08:33:17 2009
@@ -25,12 +25,10 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * ServerSocket create connections between 'host' and 'client' machines. The
- * ServerSocket listens on a well known port and upon a connection request,
- * instantiates a 'host' sockets, which carries on future communication with the
- * requesting 'client' socket, so that the server socket may continue listening
- * for connection requests. They are passive objects, having no execution thread
- * of their own to listen on.
+ * This class represents a server-side socket that waits for incoming client
+ * connections. A {@code ServerSocket} handles the requests and sends back an
+ * appropriate reply. The actual tasks that a server socket must accomplish are
+ * implemented by an internal {@code SocketImpl} instance.
  */
 public class ServerSocket {
 
@@ -49,60 +47,71 @@
     }
 
     /**
-     * Construct a ServerSocket, which is not bound to any port. The default
-     * number of pending connections may be backlogged.
+     * Constructs a new {@code ServerSocket} instance which is not bound to any
+     * port. The default number of pending connections may be backlogged.
      * 
-     * @see Socket
+     * @throws IOException
+     *             if an error occurs while creating the server socket.
      */
     public ServerSocket() throws IOException {
         impl = factory != null ? factory.createSocketImpl()
                 : new PlainServerSocketImpl();
     }
 
+    /**
+     * Unspecified constructor. Removing it theoretically breaks compatibility.
+     */
     protected ServerSocket(SocketImpl impl) {
         this.impl = impl;
     }
 
     /**
-     * Construct a ServerSocket, bound to the nominated port on the default
-     * localhost. The default number of pending connections may be backlogged.
+     * Constructs a new {@code ServerSocket} instance bound to the nominated
+     * port on the localhost. The default number of pending connections may be
+     * backlogged. If {@code aport} is 0 a free port is assigned to the socket.
      * 
      * @param aport
-     *            the port number to listen for connection requests on
-     * @see Socket
+     *            the port number to listen for connection requests on.
+     * @throws IOException
+     *             if an error occurs while creating the server socket.
      */
     public ServerSocket(int aport) throws IOException {
         this(aport, defaultBacklog(), InetAddress.ANY);
     }
 
     /**
-     * Construct a ServerSocket, bound to the nominated port on the default
-     * localhost. The number of pending connections that may be backlogged is a
-     * specified.
+     * Constructs a new {@code ServerSocket} instance bound to the nominated
+     * port on the localhost. The number of pending connections that may be
+     * backlogged is specified by {@code backlog}. If {@code aport} is 0 a free
+     * port is assigned to the socket.
      * 
      * @param aport
-     *            the port number to listen for connection requests on
+     *            the port number to listen for connection requests on.
      * @param backlog
-     *            the number of pending connection requests, before requests are
-     *            rejected
-     * @see Socket
+     *            the number of pending connection requests, before requests
+     *            will be rejected.
+     * @throws IOException
+     *             if an error occurs while creating the server socket.
      */
     public ServerSocket(int aport, int backlog) throws IOException {
         this(aport, backlog, InetAddress.ANY);
     }
 
     /**
-     * Construct a ServerSocket, bound to the nominated local host/port. The
-     * number of pending connections that may be backlogged is a specified.
+     * Constructs a new {@code ServerSocket} instance bound to the nominated
+     * local host address and port. The number of pending connections that may
+     * be backlogged is specified by {@code backlog}. If {@code aport} is 0 a
+     * free port is assigned to the socket.
      * 
      * @param aport
-     *            the port number to listen for connection requests on
+     *            the port number to listen for connection requests on.
      * @param localAddr
-     *            the local machine address to bind on
+     *            the local machine address to bind on.
      * @param backlog
-     *            the number of pending connection requests, before requests are
-     *            rejected
-     * @see Socket
+     *            the number of pending connection requests, before requests
+     *            will be rejected.
+     * @throws IOException
+     *             if an error occurs while creating the server socket.
      */
     public ServerSocket(int aport, int backlog, InetAddress localAddr)
             throws IOException {
@@ -127,12 +136,13 @@
     }
 
     /**
-     * Retrieve the first connection request and answer the 'host' socket that
-     * will conduct further communications with the requesting 'client' socket.
-     * 
-     * @return Socket the 'host' socket
-     * @exception IOException
-     *                if an error occurs while instantiating the 'host' socket
+     * Waits for an incoming request and blocks until the connection is opened.
+     * This method returns a socket object representing the just opened
+     * connection.
+     * 
+     * @return the connection representing socket.
+     * @throws IOException
+     *             if an error occurs while accepting a new connection.
      */
     public Socket accept() throws IOException {
         checkClosedAndCreate(false);
@@ -161,12 +171,12 @@
     }
 
     /**
-     * Check whether the server may listen for connection requests on
-     * <code>aport</code>. Throw an exception if the port is outside the
-     * valid range or does not satisfy the security policy.
+     * Checks whether the server may listen for connection requests on {@code
+     * aport}. Throws an exception if the port is outside the valid range
+     * {@code 0 <= aport <= 65535 }or does not satisfy the security policy.
      * 
      * @param aPort
-     *            the candidate port to listen on
+     *            the candidate port to listen on.
      */
     void checkListen(int aPort) {
         if (aPort < 0 || aPort > 65535) {
@@ -179,8 +189,11 @@
     }
 
     /**
-     * Close this server socket. Any attempt to connect to this socket
-     * thereafter will fail.
+     * Closes this server socket and its implementation. Any attempt to connect
+     * to this socket thereafter will fail.
+     *
+     * @throws IOException
+     *             if an error occurs while closing this socket.
      */
     public void close() throws IOException {
         isClosed = true;
@@ -188,7 +201,9 @@
     }
 
     /**
-     * Answer the default number of pending connections on a server socket.
+     * Answer the default number of pending connections on a server socket. If
+     * the backlog value maximum is reached, any subsequent incoming request is
+     * rejected.
      * 
      * @return int the default number of pending connection requests
      */
@@ -197,10 +212,10 @@
     }
 
     /**
-     * Answer the local IP address for this server socket. Return null if the
-     * socket is not bound. This is useful on multihomed hosts.
+     * Gets the local IP address of this server socket or {@code null} if the
+     * socket is unbound. This is useful for multihomed hosts.
      * 
-     * @return InetAddress the local address
+     * @return the local address of this server socket.
      */
     public InetAddress getInetAddress() {
         if (!isBound()) {
@@ -210,10 +225,10 @@
     }
 
     /**
-     * Answer the local port for this server socket. Return -1 if the socket is
-     * not bound.
+     * Gets the local port of this server socket or {@code -1} if the socket is
+     * unbound.
      * 
-     * @return int the local port the server is listening on
+     * @return the local port this server is listening on.
      */
     public int getLocalPort() {
         if (!isBound()) {
@@ -223,12 +238,12 @@
     }
 
     /**
-     * Answer the time-out period of this server socket. This is the time the
-     * server will wait listening for connections, before exiting.
+     * Gets the timeout period of this server socket. This is the time the
+     * server will wait listening for accepted connections before exiting.
      * 
-     * @return int the listening timeout
-     * @exception SocketException
-     *                thrown if option cannot be retrieved
+     * @return the listening timeout value of this server socket.
+     * @throws IOException
+     *             if the option cannot be retrieved.
      */
     public synchronized int getSoTimeout() throws IOException {
         if (!isCreated) {
@@ -249,13 +264,14 @@
     }
 
     /**
-     * Invoke the server socket implementation to accept a connection on the
-     * newly created <code>aSocket</code>.
+     * Invokes the server socket implementation to accept a connection on the
+     * given socket {@code aSocket}.
      * 
      * @param aSocket
-     *            the concrete socketImpl to accept the connection request on
-     * @exception IOException
-     *                thrown if connection cannot be accepted
+     *            the concrete {@code SocketImpl} to accept the connection
+     *            request on.
+     * @throws IOException
+     *             if the connection cannot be accepted.
      */
     protected final void implAccept(Socket aSocket) throws IOException {
         impl.accept(aSocket.impl);
@@ -263,15 +279,15 @@
     }
 
     /**
-     * Set the server socket implementation factory. This method may only be
-     * invoked with sufficient security and only once during the application
-     * lifetime.
+     * Sets the server socket implementation factory of this instance. This
+     * method may only be invoked with sufficient security privilege and only
+     * once during the application lifetime.
      * 
      * @param aFactory
      *            the streaming socket factory to be used for further socket
-     *            instantiations
-     * @exception IOException
-     *                thrown if the factory is already set
+     *            instantiations.
+     * @throws IOException
+     *             if the factory could not be set or is already set.
      */
     public static synchronized void setSocketFactory(SocketImplFactory aFactory)
             throws IOException {
@@ -286,12 +302,14 @@
     }
 
     /**
-     * Set the listen time-out period for this server socket.
+     * Sets the timeout period of this server socket. This is the time the
+     * server will wait listening for accepted connections before exiting. This
+     * value must be a positive number.
      * 
      * @param timeout
-     *            the time to wait for a connection request
-     * @exception SocketException
-     *                thrown if an error occurs during setting the option
+     *            the listening timeout value of this server socket.
+     * @throws SocketException
+     *             if an error occurs while setting the option.
      */
     public synchronized void setSoTimeout(int timeout) throws SocketException {
         checkClosedAndCreate(true);
@@ -302,11 +320,11 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * server socket. The <code>port</code> field is reported a zero, as there
-     * is no connection formed to the server.
+     * Returns a textual representation of this server socket including the
+     * address, port and the state. The port field is set to {@code 0} if there
+     * is no connection to the server socket.
      * 
-     * @return String the description
+     * @return the textual socket representation.
      */
     @Override
     public String toString() {
@@ -324,37 +342,40 @@
     }
 
     /**
-     * Bind the ServerSocket to the nominated local host/port. The default
-     * number of pending connections may be backlogged.
+     * Binds this server socket to the given local socket address. The default
+     * number of pending connections may be backlogged. If the {@code localAddr}
+     * is set to {@code null} the socket will be bound to an available local
+     * address on any free port of the system.
      * 
      * @param localAddr
-     *            the local machine address and port to bind on
-     * 
-     * @exception IllegalArgumentException
-     *                if the SocketAddress is not supported
-     * @exception IOException
-     *                if the socket is already bound, or a problem occurs during
-     *                the bind
+     *            the local address and port to bind on.
+     * @throws IllegalArgumentException
+     *             if the {@code SocketAddress} is not supported.
+     * @throws IOException
+     *             if the socket is already bound or a problem occurs during
+     *             binding.
      */
     public void bind(SocketAddress localAddr) throws IOException {
         bind(localAddr, defaultBacklog());
     }
 
     /**
-     * Bind the ServerSocket to the nominated local host/port. The number of
-     * pending connections that may be backlogged is a specified.
+     * Binds this server socket to the given local socket address. If the
+     * {@code localAddr} is set to {@code null} the socket will be bound to an
+     * available local address on any free port of the system. The value for
+     * {@code backlog} must e greater than {@code 0} otherwise the default value
+     * will be used.
      * 
      * @param localAddr
-     *            the local machine address and port to bind on
+     *            the local machine address and port to bind on.
      * @param backlog
-     *            the number of pending connection requests, before requests are
-     *            rejected
-     * 
-     * @exception IllegalArgumentException
-     *                if the SocketAddress is not supported
-     * @exception IOException
-     *                if the socket is already bound, or a problem occurs during
-     *                the bind
+     *            the number of pending connection requests, before requests
+     *            will be rejected.
+     * @throws IllegalArgumentException
+     *             if the {@code SocketAddress} is not supported.
+     * @throws IOException
+     *             if the socket is already bound or a problem occurs during
+     *             binding.
      */
     public void bind(SocketAddress localAddr, int backlog) throws IOException {
         checkClosedAndCreate(true);
@@ -393,8 +414,10 @@
     }
 
     /**
-     * Answer the local SocketAddress for this server socket, or null if the
-     * socket is not bound. This is useful on multihomed hosts.
+     * Gets the local socket address of this server socket or {@code null} if
+     * the socket is unbound. This is useful on multihomed hosts.
+     *
+     * @return the local socket address and port this socket is bound to.
      */
     public SocketAddress getLocalSocketAddress() {
         if (!isBound()) {
@@ -404,21 +427,26 @@
     }
 
     /**
-     * Return if the server socket is bound to a local address and port.
+     * Returns whether this server socket is bound to a local address and port
+     * or not.
+     *
+     * @return {@code true} if this socket is bound, {@code false} otherwise.
      */
     public boolean isBound() {
         return isBound;
     }
 
     /**
-     * Return if the server socket is closed.
+     * Returns whether this server socket is closed or not.
+     *
+     * @return {@code true} if this socket is closed, {@code false} otherwise.
      */
     public boolean isClosed() {
         return isClosed;
     }
 
     /**
-     * Check if the socket is closed, and throw an exception.
+     * Checks whether the socket is closed, and throws an exception.
      */
     private void checkClosedAndCreate(boolean create) throws SocketException {
         if (isClosed()) {
@@ -445,10 +473,12 @@
     }
 
     /**
-     * Set the SO_REUSEADDR socket option.
+     * Sets the value for the socket option {@code SocketOptions.SO_REUSEADDR}.
      * 
      * @param reuse
-     *            the socket SO_REUSEADDR option setting
+     *            the socket option setting.
+     * @throws SocketException
+     *             if an error occurs while setting the option value.
      */
     public void setReuseAddress(boolean reuse) throws SocketException {
         checkClosedAndCreate(true);
@@ -457,7 +487,11 @@
     }
 
     /**
-     * Get the state of the SO_REUSEADDR socket option.
+     * Gets the value of the socket option {@code SocketOptions.SO_REUSEADDR}.
+     *
+     * @return {@code true} if the option is enabled, {@code false} otherwise.
+     * @throws SocketException
+     *             if an error occurs while reading the option value.
      */
     public boolean getReuseAddress() throws SocketException {
         checkClosedAndCreate(true);
@@ -466,14 +500,14 @@
     }
 
     /**
-     * Set the socket receive buffer size.
+     * Sets the server socket receive buffer size {@code
+     * SocketOptions.SO_RCVBUF}.
      * 
      * @param size
-     *            the buffer size, in bytes
-     * 
-     * @exception java.net.SocketException
-     *                If an error occurs while setting the size or the size is
-     *                invalid.
+     *            the buffer size in bytes.
+     * @throws SocketException
+     *             if an error occurs while setting the size or the size is
+     *             invalid.
      */
     public void setReceiveBufferSize(int size) throws SocketException {
         checkClosedAndCreate(true);
@@ -484,9 +518,12 @@
     }
 
     /**
-     * Answer the socket receive buffer size (SO_RCVBUF).
+     * Gets the value for the receive buffer size socket option {@code
+     * SocketOptions.SO_RCVBUF}.
      * 
-     * @return int socket receive buffer size
+     * @return the receive buffer size of this socket.
+     * @throws SocketException
+     *             if an error occurs while reading the option value.
      */
     public int getReceiveBufferSize() throws SocketException {
         checkClosedAndCreate(true);
@@ -494,24 +531,28 @@
     }
 
     /**
-     * if ServerSocket is created by a ServerSocketChannel, returns the related
-     * ServerSocketChannel
+     * Gets the related channel if this instance was created by a
+     * {@code ServerSocketChannel}. The current implementation returns always {@code
+     * null}.
      * 
-     * @return the related ServerSocketChannel if any
+     * @return the related {@code ServerSocketChannel} if any.
      */
     public ServerSocketChannel getChannel() {
         return null;
     }
 
     /**
-     * sets performance preference for connectionTime,latency and bandwidth
-     * 
+     * Sets performance preferences for connection time, latency and bandwidth.
+     * <p>
+     * This method does currently nothing.
+     *
      * @param connectionTime
-     *            the importance of connect time
+     *            the value representing the importance of a short connecting
+     *            time.
      * @param latency
-     *            the importance of latency
+     *            the value representing the importance of low latency.
      * @param bandwidth
-     *            the importance of bandwidth
+     *            the value representing the importance of high bandwidth.
      */
     public void setPerformancePreferences(int connectionTime, int latency,
             int bandwidth) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Socket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Socket.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Socket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Socket.java Wed May  6 08:33:17 2009
@@ -30,8 +30,7 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * This class represents sockets to be used in connection-oriented (streaming)
- * protocols.
+ * Provides a client-side TCP socket.
  */
 public class Socket {
 
@@ -71,10 +70,12 @@
     }
 
     /**
-     * Construct a connection-oriented Socket. The Socket is created in the
-     * <code>factory</code> if declared, or otherwise of the default type.
+     * Creates a new unconnected socket. When a SocketImplFactory is defined it
+     * creates the internal socket implementation, otherwise the default socket
+     * implementation will be used for this socket.
      * 
      * @see SocketImplFactory
+     * @see SocketImpl
      */
     public Socket() {
         impl = factory != null ? factory.createSocketImpl()
@@ -82,19 +83,26 @@
     }
 
     /**
-     * Constructs a connection-oriented Socket with specified <code>proxy</code>.
-     * 
-     * Method <code>checkConnect</code> is called if a security manager
-     * exists, and the proxy host address and port number are passed as
-     * parameters.
+     * Creates a new unconnected socket using the given proxy type. When a
+     * {@code SocketImplFactory} is defined it creates the internal socket
+     * implementation, otherwise the default socket implementation will be used
+     * for this socket.
+     * <p>
+     * Example that will create a socket connection through a {@code SOCKS}
+     * proxy server: <br>
+     * {@code Socket sock = new Socket(new Proxy(Proxy.Type.SOCKS, new
+     * InetSocketAddress("test.domain.org", 2130)));}
      * 
      * @param proxy
-     *            the specified proxy for this Socket.
+     *            the specified proxy for this socket.
      * @throws IllegalArgumentException
-     *             if the proxy is null or of an invalid type.
+     *             if the argument {@code proxy} is {@code null} or of an
+     *             invalid type.
      * @throws SecurityException
      *             if a security manager exists and it denies the permission to
-     *             connect to proxy.
+     *             connect to the given proxy.
+     * @see SocketImplFactory
+     * @see SocketImpl
      */
     public Socket(Proxy proxy) {
         if (null == proxy || Proxy.Type.HTTP == proxy.type()) {
@@ -119,19 +127,21 @@
     }
 
     /**
-     * Construct a stream socket connected to the nominated destination
-     * host/port. By default, the socket binds it to any available port on the
-     * default localhost.
+     * Creates a new streaming socket connected to the target host specified by
+     * the parameters {@code dstName} and {@code dstPort}. The socket is bound
+     * to any available port on the local host.
      * 
      * @param dstName
-     *            the destination host to connect to
+     *            the target host name or IP address to connect to.
      * @param dstPort
-     *            the port on the destination host to connect to
-     * 
+     *            the port on the target host to connect to.
      * @throws UnknownHostException
-     *             if the host cannot be resolved
+     *             if the host name could not be resolved into an IP address.
      * @throws IOException
-     *             if an error occurs while instantiating the socket
+     *             if an error occurs while creating the socket.
+     * @throws SecurityException
+     *             if a security manager exists and it denies the permission to
+     *             connect to the given address and port.
      */
     public Socket(String dstName, int dstPort) throws UnknownHostException,
             IOException {
@@ -142,22 +152,28 @@
     }
 
     /**
-     * Construct a stream socket connected to the nominated destination
-     * host/port. The socket is bound it to the nominated localAddress/port.
-     * 
+     * Creates a new streaming socket connected to the target host specified by
+     * the parameters {@code dstName} and {@code dstPort}. On the local endpoint
+     * the socket is bound to the given address {@code localAddress} on port
+     * {@code localPort}.
+     *
+     * If {@code host} is {@code null} a loopback address is used to connect to.
+     *
      * @param dstName
-     *            the destination host to connect to
+     *            the target host name or IP address to connect to.
      * @param dstPort
-     *            the port on the destination host to connect to
+     *            the port on the target host to connect to.
      * @param localAddress
-     *            the local host address to bind to
+     *            the address on the local host to bind to.
      * @param localPort
-     *            the local port to bind to
-     * 
+     *            the port on the local host to bind to.
      * @throws UnknownHostException
-     *             if the host cannot be resolved
+     *             if the host name could not be resolved into an IP address.
      * @throws IOException
-     *             if an error occurs while instantiating the socket
+     *             if an error occurs while creating the socket.
+     * @throws SecurityException
+     *             if a security manager exists and it denies the permission to
+     *             connect to the given address and port.
      */
     public Socket(String dstName, int dstPort, InetAddress localAddress,
             int localPort) throws IOException {
@@ -168,23 +184,27 @@
     }
 
     /**
-     * Answer a new socket. This constructor is deprecated.
+     * Creates a new streaming or datagram socket connected to the target host
+     * specified by the parameters {@code hostName} and {@code port}. The socket
+     * is bound to any available port on the local host.
      * 
      * @param hostName
-     *            the host name
+     *            the target host name or IP address to connect to.
      * @param port
-     *            the port on the host
+     *            the port on the target host to connect to.
      * @param streaming
-     *            if true, answer a stream socket, else answer a a datagram
-     *            socket.
-     * 
+     *            if {@code true} a streaming socket is returned, a datagram
+     *            socket otherwise.
      * @throws UnknownHostException
-     *             if the host cannot be resolved
+     *             if the host name could not be resolved into an IP address.
      * @throws IOException
-     *             if an error occurs while instantiating the socket
-     * 
-     * @deprecated As of JDK 1.1, replaced by Socket
-     * @see #Socket(String,int)
+     *             if an error occurs while creating the socket.
+     * @throws SecurityException
+     *             if a security manager exists and it denies the permission to
+     *             connect to the given address and port.
+     * @deprecated Use {@code Socket(String, int)} instead of this for streaming
+     *             sockets or an appropriate constructor of {@code
+     *             DatagramSocket} for UDP transport.
      */
     @Deprecated
     public Socket(String hostName, int port, boolean streaming)
@@ -196,17 +216,19 @@
     }
 
     /**
-     * Construct a stream socket connected to the nominated destination host
-     * address/port. By default, the socket binds it to any available port on
-     * the default localhost.
+     * Creates a new streaming socket connected to the target host specified by
+     * the parameters {@code dstAddress} and {@code dstPort}. The socket is
+     * bound to any available port on the local host.
      * 
      * @param dstAddress
-     *            the destination host address to connect to
+     *            the target host address to connect to.
      * @param dstPort
-     *            the port on the destination host to connect to
-     * 
+     *            the port on the target host to connect to.
      * @throws IOException
-     *             if an error occurs while instantiating the socket
+     *             if an error occurs while creating the socket.
+     * @throws SecurityException
+     *             if a security manager exists and it denies the permission to
+     *             connect to the given address and port.
      */
     public Socket(InetAddress dstAddress, int dstPort) throws IOException {
         this();
@@ -215,20 +237,24 @@
     }
 
     /**
-     * Construct a stream socket connected to the nominated destination host
-     * address/port. The socket is bound it to the nominated localAddress/port.
+     * Creates a new streaming socket connected to the target host specified by
+     * the parameters {@code dstAddress} and {@code dstPort}. On the local
+     * endpoint the socket is bound to the given address {@code localAddress} on
+     * port {@code localPort}.
      * 
      * @param dstAddress
-     *            the destination host address to connect to
+     *            the target host address to connect to.
      * @param dstPort
-     *            the port on the destination host to connect to
+     *            the port on the target host to connect to.
      * @param localAddress
-     *            the local host address to bind to
+     *            the address on the local host to bind to.
      * @param localPort
-     *            the local port to bind to
-     * 
+     *            the port on the local host to bind to.
      * @throws IOException
-     *             if an error occurs while instantiating the socket
+     *             if an error occurs while creating the socket.
+     * @throws SecurityException
+     *             if a security manager exists and it denies the permission to
+     *             connect to the given address and port.
      */
     public Socket(InetAddress dstAddress, int dstPort,
             InetAddress localAddress, int localPort) throws IOException {
@@ -238,23 +264,25 @@
     }
 
     /**
-     * Answer a new socket. This constructor is deprecated.
+     * Creates a new streaming or datagram socket connected to the target host
+     * specified by the parameters {@code addr} and {@code port}. The socket is
+     * bound to any available port on the local host.
      * 
      * @param addr
-     *            the internet address
+     *            the Internet address to connect to.
      * @param port
-     *            the port on the host
+     *            the port on the target host to connect to.
      * @param streaming
-     *            if true, answer a stream socket, else answer a datagram
-     *            socket.
-     * 
-     * @throws UnknownHostException
-     *             if the host cannot be resolved
+     *            if {@code true} a streaming socket is returned, a datagram
+     *            socket otherwise.
      * @throws IOException
-     *             if an error occurs while instantiating the socket
-     * 
-     * @deprecated As of JDK 1.1, replaced by Socket
-     * @see #Socket(InetAddress,int)
+     *             if an error occurs while creating the socket.
+     * @throws SecurityException
+     *             if a security manager exists and it denies the permission to
+     *             connect to the given address and port.
+     * @deprecated Use {@code Socket(InetAddress, int)} instead of this for
+     *             streaming sockets or an appropriate constructor of {@code
+     *             DatagramSocket} for UDP transport.
      */
     @Deprecated
     public Socket(InetAddress addr, int port, boolean streaming)
@@ -265,27 +293,25 @@
     }
 
     /**
-     * Creates an unconnected socket, wrapping the <code>socketImpl</code>
-     * argument.
+     * Creates an unconnected socket with the given socket implementation.
      * 
      * @param anImpl
-     *            the socket to wrap
-     * 
+     *            the socket implementation to be used.
      * @throws SocketException
-     *             if an error occurs assigning the implementation
+     *             if an error occurs while creating the socket.
      */
     protected Socket(SocketImpl anImpl) throws SocketException {
         impl = anImpl;
     }
 
     /**
-     * Check the connection destination satisfies the security policy and is in
-     * the valid port range.
+     * Checks whether the connection destination satisfies the security policy
+     * and the validity of the port range.
      * 
      * @param destAddr
-     *            the destination host address
+     *            the destination host address.
      * @param dstPort
-     *            the port on the destination host
+     *            the port on the destination host.
      */
     void checkDestination(InetAddress destAddr, int dstPort) {
         if (dstPort < 0 || dstPort > 65535) {
@@ -294,11 +320,13 @@
         checkConnectPermission(destAddr.getHostName(), dstPort);
     }
 
-    /*
-     * Checks the connection destination satisfies the security policy.
+    /**
+     * Checks whether the connection destination satisfies the security policy.
      * 
-     * @param hostname the destination hostname @param dstPort the port on the
-     * destination host
+     * @param hostname
+     *            the destination hostname.
+     * @param dstPort
+     *            the port on the destination host.
      */
     private void checkConnectPermission(String hostname, int dstPort) {
         SecurityManager security = System.getSecurityManager();
@@ -308,10 +336,11 @@
     }
 
     /**
-     * Close the socket. It is not valid to use the socket thereafter.
+     * Closes the socket. It is not possible to reconnect or rebind to this
+     * socket thereafter which means a new socket instance has to be created.
      * 
      * @throws IOException
-     *             if an error occurs during the close
+     *             if an error occurs while closing the socket.
      */
     public synchronized void close() throws IOException {
         isClosed = true;
@@ -319,11 +348,10 @@
     }
 
     /**
-     * Returns an {@link InetAddress} instance representing the address this
-     * socket has connected to.
+     * Gets the IP address of the target host this socket is connected to.
      * 
-     * @return if this socket is connected, the address it is connected to. A
-     *         <code>null</code> return signifies no connection has been made.
+     * @return the IP address of the connected target host or {@code null} if
+     *         this socket is not yet connected.
      */
     public InetAddress getInetAddress() {
         if (!isConnected()) {
@@ -333,15 +361,12 @@
     }
 
     /**
-     * Answer the socket input stream, to read byte data off the socket. Note,
-     * multiple input streams may be created on a single socket.
-     * 
-     * @return a byte oriented read stream for this socket
+     * Gets an input stream to read data from this socket.
      * 
+     * @return the byte-oriented input stream.
      * @throws IOException
-     *             if an error occurs creating the stream
-     * 
-     * @see org.apache.harmony.luni.net.SocketInputStream
+     *             if an error occurs while creating the input stream or the
+     *             socket is in an invalid state.
      */
     public InputStream getInputStream() throws IOException {
         checkClosedAndCreate(false);
@@ -352,12 +377,13 @@
     }
 
     /**
-     * Answer the SO_KEEPALIVE option for this socket.
-     * 
-     * @return the socket SO_KEEPALIVE option setting
+     * Gets the setting of the socket option {@code SocketOptions.SO_KEEPALIVE}.
      * 
+     * @return {@code true} if the {@code SocketOptions.SO_KEEPALIVE} is
+     *         enabled, {@code false} otherwise.
      * @throws SocketException
-     *             if an error occurs on the option access
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_KEEPALIVE
      */
     public boolean getKeepAlive() throws SocketException {
         checkClosedAndCreate(true);
@@ -366,10 +392,10 @@
     }
 
     /**
-     * Returns an {@link InetAddress} instance representing the <i>local</i>
-     * address this socket is bound to.
+     * Gets the local IP address this socket is bound to.
      * 
-     * @return the local address that this socket has bound to
+     * @return the local IP address of this socket or {@code InetAddress.ANY} if
+     *         the socket is unbound.
      */
     public InetAddress getLocalAddress() {
         if (!isBound()) {
@@ -380,9 +406,10 @@
     }
 
     /**
-     * Answer the local port to which the socket is bound.
+     * Gets the local port this socket is bound to.
      * 
-     * @return the local port to which the socket is bound
+     * @return the local port of this socket or {@code -1} if the socket is
+     *         unbound.
      */
     public int getLocalPort() {
         if (!isBound()) {
@@ -392,15 +419,12 @@
     }
 
     /**
-     * Answer the socket output stream, for writing byte data on the socket.
-     * Note, multiplie output streams may be created on a single socket.
-     * 
-     * @return OutputStream a byte oriented write stream for this socket
+     * Gets an output stream to write data into this socket.
      * 
+     * @return the byte-oriented output stream.
      * @throws IOException
-     *             if an error occurs creating the stream
-     * 
-     * @see org.apache.harmony.luni.net.SocketOutputStream
+     *             if an error occurs while creating the output stream or the
+     *             socket is in an invalid state.
      */
     public OutputStream getOutputStream() throws IOException {
         checkClosedAndCreate(false);
@@ -411,11 +435,10 @@
     }
 
     /**
-     * Returns the number of the remote port this socket is connected to.
+     * Gets the port number of the target host this socket is connected to.
      * 
-     * @return int the remote port number that this socket has connected to. A
-     *         return of <code>0</code> (zero) indicates that there is no
-     *         connection in place.
+     * @return the port number of the connected target host or {@code 0} if this
+     *         socket is not yet connected.
      */
     public int getPort() {
         if (!isConnected()) {
@@ -425,13 +448,13 @@
     }
 
     /**
-     * Answer the linger-on-close timeout for this socket (the SO_LINGER value).
-     * 
-     * @return this socket's SO_LINGER value. A value of <code>-1</code> will
-     *         be returned if the option is not enabled.
+     * Gets the value of the socket option {@code SocketOptions.SO_LINGER}.
      * 
+     * @return the current value of the option {@code SocketOptions.SO_LINGER}
+     *         or {@code -1} if this option is disabled.
      * @throws SocketException
-     *             if an error occurs on querying this property
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_LINGER
      */
     public int getSoLinger() throws SocketException {
         checkClosedAndCreate(true);
@@ -439,12 +462,12 @@
     }
 
     /**
-     * Answer the socket receive buffer size (SO_RCVBUF).
-     * 
-     * @return socket receive buffer size
+     * Gets the receive buffer size of this socket.
      * 
+     * @return the current value of the option {@code SocketOptions.SO_RCVBUF}.
      * @throws SocketException
-     *             if an error occurs on the option access
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_RCVBUF
      */
     public synchronized int getReceiveBufferSize() throws SocketException {
         checkClosedAndCreate(true);
@@ -452,12 +475,12 @@
     }
 
     /**
-     * Answer the socket send buffer size (SO_SNDBUF).
-     * 
-     * @return socket send buffer size
+     * Gets the send buffer size of this socket.
      * 
+     * @return the current value of the option {@code SocketOptions.SO_SNDBUF}.
      * @throws SocketException
-     *             if an error occurs on the option access
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_SNDBUF
      */
     public synchronized int getSendBufferSize() throws SocketException {
         checkClosedAndCreate(true);
@@ -465,14 +488,14 @@
     }
 
     /**
-     * Answer the socket read timeout. The SO_TIMEOUT option, a value of 0
-     * indicates it is disabled and a read operation will block indefinitely
-     * waiting for data.
-     * 
-     * @return the socket read timeout
+     * Gets the timeout for this socket during which a reading operation shall
+     * block while waiting for data.
      * 
+     * @return the current value of the option {@code SocketOptions.SO_TIMEOUT}
+     *         or {@code 0} which represents an infinite timeout.
      * @throws SocketException
-     *             if an error occurs on the option access
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_TIMEOUT
      */
     public synchronized int getSoTimeout() throws SocketException {
         checkClosedAndCreate(true);
@@ -480,13 +503,13 @@
     }
 
     /**
-     * Answer true if the socket is using Nagle's algorithm. The TCP_NODELAY
-     * option setting.
-     * 
-     * @return the socket TCP_NODELAY option setting
-     * 
+     * Gets the setting of the socket option {@code SocketOptions.TCP_NODELAY}.
+     *
+     * @return {@code true} if the {@code SocketOptions.TCP_NODELAY} is enabled,
+     *         {@code false} otherwise.
      * @throws SocketException
-     *             if an error occurs on the option access
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#TCP_NODELAY
      */
     public boolean getTcpNoDelay() throws SocketException {
         checkClosedAndCreate(true);
@@ -495,13 +518,13 @@
     }
 
     /**
-     * Set the SO_KEEPALIVE option for this socket.
+     * Sets the state of the {@code SocketOptions.SO_KEEPALIVE} for this socket.
      * 
      * @param value
-     *            the socket SO_KEEPALIVE option setting
-     * 
+     *            the state whether this option is enabled or not.
      * @throws SocketException
-     *             if an error occurs setting the option
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#SO_KEEPALIVE
      */
     public void setKeepAlive(boolean value) throws SocketException {
         if (impl != null) {
@@ -512,13 +535,13 @@
     }
 
     /**
-     * Specifies the application's socket implementation factory. This may only
-     * be executed the once over the lifetime of the application.
+     * Sets the internal factory for creating socket implementations. This may
+     * only be executed once during the lifetime of the application.
      * 
      * @param fac
-     *            the socket factory to set
-     * @exception IOException
-     *                thrown if the factory has already been set
+     *            the socket implementation factory to be set.
+     * @throws IOException
+     *             if the factory has been already set.
      */
     public static synchronized void setSocketImplFactory(SocketImplFactory fac)
             throws IOException {
@@ -533,14 +556,15 @@
     }
 
     /**
-     * Set the socket send buffer size.
+     * Sets the send buffer size of this socket.
      * 
      * @param size
-     *            the buffer size, in bytes
-     * 
+     *            the buffer size in bytes. This value must be a positive number
+     *            greater than {@code 0}.
      * @throws SocketException
-     *             if an error occurs while setting the size or the size is
-     *             invalid.
+     *             if an error occurs while setting the size or the given value
+     *             is an invalid size.
+     * @see SocketOptions#SO_SNDBUF
      */
     public synchronized void setSendBufferSize(int size) throws SocketException {
         checkClosedAndCreate(true);
@@ -551,14 +575,15 @@
     }
 
     /**
-     * Set the socket receive buffer size.
+     * Sets the receive buffer size of this socket.
      * 
      * @param size
-     *            the buffer size, in bytes
-     * 
+     *            the buffer size in bytes. This value must be a positive number
+     *            greater than {@code 0}.
      * @throws SocketException
-     *             tf an error occurs while setting the size or the size is
-     *             invalid.
+     *             if an error occurs while setting the size or the given value
+     *             is an invalid size.
+     * @see SocketOptions#SO_RCVBUF
      */
     public synchronized void setReceiveBufferSize(int size)
             throws SocketException {
@@ -570,16 +595,17 @@
     }
 
     /**
-     * Set the SO_LINGER option, with the specified time, in seconds. The
-     * SO_LINGER option is silently limited to 65535 seconds.
+     * Sets the state of the {@code SocketOptions.SO_LINGER} with the given
+     * timeout in seconds. The timeout value for this option is silently limited
+     * to the maximum of {@code 65535}.
      * 
      * @param on
-     *            if linger is enabled
+     *            the state whether this option is enabled or not.
      * @param timeout
-     *            the linger timeout value, in seconds
-     * 
+     *            the linger timeout value in seconds.
      * @throws SocketException
-     *             if an error occurs setting the option
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#SO_LINGER
      */
     public void setSoLinger(boolean on, int timeout) throws SocketException {
         checkClosedAndCreate(true);
@@ -591,15 +617,17 @@
     }
 
     /**
-     * Set the read timeout on this socket. The SO_TIMEOUT option, is specified
-     * in milliseconds. The read operation will block indefinitely for a zero
-     * value.
+     * Sets the reading timeout in milliseconds for this socket. The read
+     * operation will block indefinitely if this option value is set to {@code
+     * 0}. The timeout must be set before calling the read operation. A
+     * {@code SocketTimeoutException} is thrown when this timeout expires.
      * 
      * @param timeout
-     *            the read timeout value
-     * 
+     *            the reading timeout value as number greater than {@code 0} or
+     *            {@code 0} for an infinite timeout.
      * @throws SocketException
-     *             if an error occurs setting the option
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#SO_TIMEOUT
      */
     public synchronized void setSoTimeout(int timeout) throws SocketException {
         checkClosedAndCreate(true);
@@ -610,14 +638,13 @@
     }
 
     /**
-     * Set whether the socket is to use Nagle's algorithm. The TCP_NODELAY
-     * option setting.
+     * Sets the state of the {@code SocketOptions.TCP_NODELAY} for this socket.
      * 
      * @param on
-     *            the socket TCP_NODELAY option setting
-     * 
+     *            the state whether this option is enabled or not.
      * @throws SocketException
-     *             if an error occurs setting the option
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#TCP_NODELAY
      */
     public void setTcpNoDelay(boolean on) throws SocketException {
         checkClosedAndCreate(true);
@@ -629,17 +656,16 @@
      * then connects it to the nominated destination address/port.
      * 
      * @param dstAddress
-     *            the destination host address
+     *            the destination host address.
      * @param dstPort
-     *            the port on the destination host
+     *            the port on the destination host.
      * @param localAddress
-     *            the address on the local machine to bind
+     *            the address on the local machine to bind.
      * @param localPort
-     *            the port on the local machine to bind
-     * 
+     *            the port on the local machine to bind.
      * @throws IOException
-     *             thrown if a error occurs during the bind or connect
-     *             operations
+     *             thrown if an error occurs during the bind or connect
+     *             operations.
      */
     void startupSocket(InetAddress dstAddress, int dstPort,
             InetAddress localAddress, int localPort, boolean streaming)
@@ -669,10 +695,10 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
+     * Returns a {@code String} containing a concise, human-readable description of the
      * socket.
      * 
-     * @return the description
+     * @return the textual representation of this socket.
      */
     @Override
     public String toString() {
@@ -683,12 +709,14 @@
     }
 
     /**
-     * Shutdown the input portion of the socket.
+     * Closes the input stream of this socket. Any further data sent to this
+     * socket will be discarded. Reading from this socket after this method has
+     * been called will return the value {@code EOF}.
      * 
      * @throws IOException
-     *             if an error occurs while closing the socket input
+     *             if an error occurs while closing the socket input stream.
      * @throws SocketException
-     *             if the socket is closed
+     *             if the input stream is already closed.
      */
     public void shutdownInput() throws IOException {
         if (isInputShutdown()) {
@@ -700,12 +728,14 @@
     }
 
     /**
-     * Shutdown the output portion of the socket.
+     * Closes the output stream of this socket. All buffered data will be sent
+     * followed by the termination sequence. Writing to the closed output stream
+     * will cause an {@code IOException}.
      * 
      * @throws IOException
-     *             if an error occurs while closing the socket output
+     *             if an error occurs while closing the socket output stream.
      * @throws SocketException
-     *             if the socket is closed
+     *             if the output stream is already closed.
      */
     public void shutdownOutput() throws IOException {
         if (isOutputShutdown()) {
@@ -717,11 +747,11 @@
     }
 
     /**
-     * Check if the socket is closed, and throw an exception. Otherwise create
-     * the underlying SocketImpl.
+     * Checks whether the socket is closed, and throws an exception. Otherwise
+     * creates the underlying SocketImpl.
      * 
      * @throws SocketException
-     *             if the socket is closed
+     *             if the socket is closed.
      */
     private void checkClosedAndCreate(boolean create) throws SocketException {
         if (isClosed()) {
@@ -758,12 +788,11 @@
     }
 
     /**
-     * Answer the local SocketAddress for this socket, or null if the socket is
-     * not bound.
-     * <p>
-     * This is useful on multihomed hosts.
+     * Gets the local address and port of this socket as a SocketAddress or
+     * {@code null} if the socket is unbound. This is useful on multihomed
+     * hosts.
      * 
-     * @return the local socket address
+     * @return the bound local socket address and port.
      */
     public SocketAddress getLocalSocketAddress() {
         if (!isBound()) {
@@ -773,10 +802,10 @@
     }
 
     /**
-     * Answer the remote SocketAddress for this socket, or null if the socket is
-     * not connected.
+     * Gets the remote address and port of this socket as a {@code
+     * SocketAddress} or {@code null} if the socket is not connected.
      * 
-     * @return the remote socket address
+     * @return the remote socket address and port.
      */
     public SocketAddress getRemoteSocketAddress() {
         if (!isConnected()) {
@@ -786,46 +815,46 @@
     }
 
     /**
-     * Return if the socket is bound to a local address and port.
+     * Returns whether this socket is bound to a local address and port.
      * 
-     * @return <code>true</code> if the socket is bound to a local address,
-     *         <code>false</code> otherwise.
+     * @return {@code true} if the socket is bound to a local address, {@code
+     *         false} otherwise.
      */
     public boolean isBound() {
         return isBound;
     }
 
     /**
-     * Return if the socket is connected.
+     * Returns whether this socket is connected to a remote host.
      * 
-     * @return <code>true</code> if the socket is connected,
-     *         <code>false</code> otherwise.
+     * @return {@code true} if the socket is connected, {@code false} otherwise.
      */
     public boolean isConnected() {
         return isConnected;
     }
 
     /**
-     * Return if the socket is closed.
+     * Returns whether this socket is closed.
      * 
-     * @return <code>true</code> if the socket is closed, <code>false</code>
-     *         otherwise.
+     * @return {@code true} if the socket is closed, {@code false} otherwise.
      */
     public boolean isClosed() {
         return isClosed;
     }
 
     /**
-     * Bind the Socket to the nominated local host/port.
+     * Binds this socket to the given local host address and port specified by
+     * the SocketAddress {@code localAddr}. If {@code localAddr} is set to
+     * {@code null}, this socket will be bound to an available local address on
+     * any free port.
      * 
      * @param localAddr
-     *            the local machine address and port to bind on
-     * 
+     *            the specific address and port on the local machine to bind to.
      * @throws IllegalArgumentException
-     *             if the SocketAddress is not supported
+     *             if the given SocketAddress is invalid or not supported.
      * @throws IOException
-     *             if the socket is already bound, or a problem occurs during
-     *             the bind
+     *             if the socket is already bound or an error occurs while
+     *             binding.
      */
     public void bind(SocketAddress localAddr) throws IOException {
         checkClosedAndCreate(true);
@@ -860,37 +889,38 @@
     }
 
     /**
-     * Connect the Socket to the host/port specified by the SocketAddress.
+     * Connects this socket to the given remote host address and port specified
+     * by the SocketAddress {@code remoteAddr}.
      * 
      * @param remoteAddr
-     *            the remote machine address and port to connect to
-     * 
+     *            the address and port of the remote host to connect to.
      * @throws IllegalArgumentException
-     *             if the SocketAddress is not supported
+     *             if the given SocketAddress is invalid or not supported.
      * @throws IOException
-     *             if the socket is already connected, or a problem occurs
-     *             during the connect
+     *             if the socket is already connected or an error occurs while
+     *             connecting.
      */
     public void connect(SocketAddress remoteAddr) throws IOException {
         connect(remoteAddr, 0);
     }
 
     /**
-     * Connect the Socket to the host/port specified by the SocketAddress with a
-     * specified timeout.
+     * Connects this socket to the given remote host address and port specified
+     * by the SocketAddress {@code remoteAddr} with the specified timeout. The
+     * connecting method will block until the connection is established or an
+     * error occurred.
      * 
      * @param remoteAddr
-     *            the remote machine address and port to connect to
+     *            the address and port of the remote host to connect to.
      * @param timeout
-     *            the millisecond timeout value, the connect will block
-     *            indefinitely for a zero value.
-     * 
+     *            the timeout value in milliseconds or {@code 0} for an infinite
+     *            timeout.
      * @throws IllegalArgumentException
-     *             if the timeout is negative, or the SocketAddress is not
-     *             supported
+     *             if the given SocketAddress is invalid or not supported or the
+     *             timeout value is negative.
      * @throws IOException
-     *             if the socket is already connected, or a problem occurs
-     *             during the connect
+     *             if the socket is already connected or an error occurs while
+     *             connecting.
      */
     public void connect(SocketAddress remoteAddr, int timeout)
             throws IOException {
@@ -939,33 +969,35 @@
     }
 
     /**
-     * Return if {@link #shutdownInput} has been called.
+     * Returns whether the incoming channel of the socket has already been
+     * closed.
      * 
-     * @return <code>true</code> if <code>shutdownInput</code> has been
-     *         called, <code>false</code> otherwise.
+     * @return {@code true} if reading from this socket is not possible anymore,
+     *         {@code false} otherwise.
      */
     public boolean isInputShutdown() {
         return isInputShutdown;
     }
 
     /**
-     * Return if {@link #shutdownOutput} has been called.
+     * Returns whether the outgoing channel of the socket has already been
+     * closed.
      * 
-     * @return <code>true</code> if <code>shutdownOutput</code> has been
-     *         called, <code>false</code> otherwise.
+     * @return {@code true} if writing to this socket is not possible anymore,
+     *         {@code false} otherwise.
      */
     public boolean isOutputShutdown() {
         return isOutputShutdown;
     }
 
     /**
-     * Set the SO_REUSEADDR socket option.
+     * Sets the state of the {@code SocketOptions.SO_REUSEADDR} for this socket.
      * 
      * @param reuse
-     *            the socket SO_REUSEADDR option setting
-     * 
+     *            the state whether this option is enabled or not.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#SO_REUSEADDR
      */
     public void setReuseAddress(boolean reuse) throws SocketException {
         checkClosedAndCreate(true);
@@ -974,13 +1006,13 @@
     }
 
     /**
-     * Get the state of the SO_REUSEADDR socket option.
-     * 
-     * @return <code>true</code> if the SO_REUSEADDR is enabled,
-     *         <code>false</code> otherwise.
+     * Gets the setting of the socket option {@code SocketOptions.SO_REUSEADDR}.
      * 
+     * @return {@code true} if the {@code SocketOptions.SO_REUSEADDR} is
+     *         enabled, {@code false} otherwise.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_REUSEADDR
      */
     public boolean getReuseAddress() throws SocketException {
         checkClosedAndCreate(true);
@@ -989,14 +1021,15 @@
     }
 
     /**
-     * Set the SO_OOBINLINE socket option. When this option is enabled, out of
-     * band data is recieved in the normal data stream.
+     * Sets the state of the {@code SocketOptions.SO_OOBINLINE} for this socket.
+     * When this option is enabled urgent data can be received in-line with
+     * normal data.
      * 
      * @param oobinline
-     *            the socket SO_OOBINLINE option setting
-     * 
+     *            whether this option is enabled or not.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#SO_OOBINLINE
      */
     public void setOOBInline(boolean oobinline) throws SocketException {
         checkClosedAndCreate(true);
@@ -1005,13 +1038,13 @@
     }
 
     /**
-     * Get the state of the SO_OOBINLINE socket option.
-     * 
-     * @return <code>true</code> if the SO_OOBINLINE is enabled,
-     *         <code>false</code> otherwise.
+     * Gets the setting of the socket option {@code SocketOptions.SO_OOBINLINE}.
      * 
+     * @return {@code true} if the {@code SocketOptions.SO_OOBINLINE} is
+     *         enabled, {@code false} otherwise.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#SO_OOBINLINE
      */
     public boolean getOOBInline() throws SocketException {
         checkClosedAndCreate(true);
@@ -1020,13 +1053,16 @@
     }
 
     /**
-     * Set the IP_TOS socket option.
+     * Sets the value of the {@code SocketOptions.IP_TOS} for this socket. See
+     * the specification RFC 1349 for more information about the type of service
+     * field.
      * 
      * @param value
-     *            the socket IP_TOS setting
-     * 
+     *            the value to be set for this option with a valid range of
+     *            {@code 0-255}.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if an error occurs while setting the option.
+     * @see SocketOptions#IP_TOS
      */
     public void setTrafficClass(int value) throws SocketException {
         checkClosedAndCreate(true);
@@ -1037,12 +1073,12 @@
     }
 
     /**
-     * Get the IP_TOS socket option.
-     * 
-     * @return the IP_TOS socket option value
+     * Gets the value of the socket option {@code SocketOptions.IP_TOS}.
      * 
+     * @return the value which represents the type of service.
      * @throws SocketException
-     *             if the option is invalid
+     *             if an error occurs while reading the socket option.
+     * @see SocketOptions#IP_TOS
      */
     public int getTrafficClass() throws SocketException {
         checkClosedAndCreate(true);
@@ -1050,13 +1086,13 @@
     }
 
     /**
-     * Send the single byte of urgent data on the socket.
+     * Sends the given single byte data which is represented by the lowest octet
+     * of {@code value} as "TCP urgent data".
      * 
      * @param value
-     *            the byte of urgent data
-     * 
-     * @exception IOException
-     *                when an error occurs sending urgent data
+     *            the byte of urgent data to be sent.
+     * @throws IOException
+     *             if an error occurs while sending urgent data.
      */
     public void sendUrgentData(int value) throws IOException {
         if (!impl.supportsUrgentData()) {
@@ -1066,7 +1102,8 @@
     }
 
     /**
-     * Set the appropriate flags for a Socket created by ServerSocket.accept().
+     * Set the appropriate flags for a socket created by {@code
+     * ServerSocket.accept()}.
      * 
      * @see ServerSocket#implAccept
      */
@@ -1081,24 +1118,27 @@
     }
 
     /**
-     * if Socket is created by a SocketChannel, returns the related
-     * SocketChannel
+     * Gets the SocketChannel of this socket, if one is available. The current
+     * implementation of this method returns always {@code null}.
      * 
-     * @return the related SocketChannel
+     * @return the related SocketChannel or {@code null} if no channel exists.
      */
     public SocketChannel getChannel() {
         return null;
     }
 
     /**
-     * sets performance preference for connectionTime,latency and bandwidth
-     * 
+     * Sets performance preferences for connectionTime, latency and bandwidth.
+     * <p>
+     * This method does currently nothing.
+     *
      * @param connectionTime
-     *            the importance of connect time
+     *            the value representing the importance of a short connecting
+     *            time.
      * @param latency
-     *            the importance of latency
+     *            the value representing the importance of low latency.
      * @param bandwidth
-     *            the importance of bandwidth
+     *            the value representing the importance of high bandwidth.
      */
     public void setPerformancePreferences(int connectionTime, int latency,
             int bandwidth) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketAddress.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketAddress.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketAddress.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketAddress.java Wed May  6 08:33:17 2009
@@ -19,8 +19,16 @@
 
 import java.io.Serializable;
 
+/**
+ * This abstract class represents a protocol-independent base for
+ * socket-endpoint representing classes. The class has to be implemented
+ * according to a specific protocol.
+ */
 public abstract class SocketAddress implements Serializable {
 
+    /**
+     * Creates a new {@code SocketAddress} instance.
+     */
     public SocketAddress() {
         super();
     }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketException.java Wed May  6 08:33:17 2009
@@ -20,26 +20,27 @@
 import java.io.IOException;
 
 /**
- * This SocketException may be thrown during socket creation or setting options,
- * and is the superclass of all other socket related exceptions.
+ * This {@code SocketException} may be thrown during socket creation or setting
+ * options, and is the superclass of all other socket related exceptions.
  */
 public class SocketException extends IOException {
 
     private static final long serialVersionUID = -5935874303556886934L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code SocketException} instance with its walkback
+     * filled in.
      */
     public SocketException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code SocketException} instance with its walkback and
+     * message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message of this exception.
      */
     public SocketException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImpl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImpl.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImpl.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImpl.java Wed May  6 08:33:17 2009
@@ -27,27 +27,34 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * The abstract superclass of all classes that implement streaming sockets.
- * 
- * Streaming sockets are wrapped by two classes, ServerSocket and Socket at the
- * server and client end of a connection respectively. At the server there are
- * two types of sockets engaged in communication, the <code>ServerSocket</code>
- * on a well known port (hereafter referred to as the listener) used to
- * establish a connection and the resulting <code>Socket</code> (hereafter
- * referred to as host).
- * 
- * Some of the <code>SocketImpl</code> instance variable values must be
- * interpreted in the context of the wrapper. See the getter methods for these
- * details.
+ * This class is the base of all streaming socket implementation classes.
+ * Streaming sockets are wrapped by two classes, {@code ServerSocket} and
+ * {@code Socket} at the server and client end of a connection. At the server,
+ * there are two types of sockets engaged in communication, the {@code
+ * ServerSocket} on a well known port (referred to as listener) used to
+ * establish a connection and the resulting {@code Socket} (referred to as
+ * host).
  */
 public abstract class SocketImpl implements SocketOptions {
 
+    /**
+     * The remote address this socket is connected to.
+     */
     protected InetAddress address;
 
+    /**
+     * The remote port this socket is connected to.
+     */
     protected int port;
 
+    /**
+     * The file descriptor of this socket.
+     */
     protected FileDescriptor fd;
 
+    /**
+     * The local port this socket is connected to.
+     */
     protected int localport;
 
     INetworkSystem netImpl;
@@ -59,7 +66,7 @@
     boolean shutdownInput;
 
     /**
-     * Construct a connection-oriented SocketImpl.
+     * Creates a new connection-oriented socket implementation.
      * 
      * @see SocketImplFactory
      */
@@ -68,184 +75,184 @@
     }
 
     /**
-     * Accepts a connection on the provided socket.
+     * Waits for an incoming request and blocks until the connection is opened
+     * on the given socket.
      * 
      * @param newSocket
-     *            the socket to accept connections on
-     * @exception SocketException
-     *                if an error occurs while accepting
+     *            the socket to accept connections on.
+     * @throws IOException
+     *             if an error occurs while accepting a new connection.
      */
     protected abstract void accept(SocketImpl newSocket) throws IOException;
 
     /**
-     * Answer the number of bytes that may be read from this socket without
-     * blocking. This call does not block.
+     * Returns the available number of bytes which are readable from this socket
+     * without blocking.
      * 
-     * @return the number of bytes that may be read without blocking
-     * @exception SocketException
-     *                if an error occurs while peeking
+     * @return the number of bytes that may be read without blocking.
+     * @throws IOException
+     *             if an error occurs while reading the number of bytes.
      */
     protected abstract int available() throws IOException;
 
     /**
-     * Binds this socket to the specified local host/port.
+     * Binds this socket to the specified local host address and port number.
      * 
      * @param address
-     *            the local machine address to bind the socket to
+     *            the local machine address to bind this socket to.
      * @param port
-     *            the port on the local machine to bind the socket to
-     * @exception IOException
-     *                if an error occurs while binding
+     *            the port on the local machine to bind this socket to.
+     * @throws IOException
+     *             if an error occurs while binding this socket.
      */
     protected abstract void bind(InetAddress address, int port)
             throws IOException;
 
     /**
-     * Close the socket. Usage thereafter is invalid.
+     * Closes this socket. This makes later access invalid.
      * 
-     * @exception IOException
-     *                if an error occurs while closing
+     * @throws IOException
+     *             if an error occurs while closing this socket.
      */
     protected abstract void close() throws IOException;
 
     /**
-     * Connects this socket to the specified remote host/port.
+     * Connects this socket to the specified remote host and port number.
      * 
      * @param host
-     *            the remote host to connect to
+     *            the remote host this socket has to be connected to.
      * @param port
-     *            the remote port to connect to
-     * @exception IOException
-     *                if an error occurs while connecting
+     *            the remote port on which this socket has to be connected.
+     * @throws IOException
+     *             if an error occurs while connecting to the remote host.
      */
     protected abstract void connect(String host, int port) throws IOException;
 
     /**
-     * Connects this socket to the specified remote host address/port.
-     * 
+     * Connects this socket to the specified remote host address and port
+     * number.
+     *
      * @param address
-     *            the remote host address to connect to
+     *            the remote host address this socket has to be connected to.
      * @param port
-     *            the remote port to connect to
-     * @exception IOException
-     *                if an error occurs while connecting
+     *            the remote port on which this socket has to be connected.
+     * @throws IOException
+     *             if an error occurs while connecting to the remote host.
      */
     protected abstract void connect(InetAddress address, int port)
             throws IOException;
 
     /**
-     * Creates a new unconnected socket. If streaming is true, create a stream
-     * socket, else a datagram socket.
+     * Creates a new unconnected socket. The argument {@code isStreaming}
+     * defines whether the new socket is a streaming or a datagram socket.
      * 
      * @param isStreaming
-     *            true, if the socket is type streaming
-     * @exception SocketException
-     *                if an error occurs while creating the socket
+     *            defines whether the type of the new socket is streaming or
+     *            datagram.
+     * @throws IOException
+     *             if an error occurs while creating the socket.
      */
     protected abstract void create(boolean isStreaming) throws IOException;
 
     /**
-     * Answer the socket's file descriptor.
+     * Gets the file descriptor of this socket.
      * 
-     * @return FileDescriptor the socket FileDescriptor
+     * @return the file descriptor of this socket.
      */
     protected FileDescriptor getFileDescriptor() {
         return fd;
     }
 
     /**
-     * Answer the socket's address. Referring to the class comment: Listener:
-     * The local machines IP address to which this socket is bound. Host: The
-     * client machine, to which this socket is connected. Client: The host
-     * machine, to which this socket is connected.
+     * Gets the remote address this socket is connected to.
      * 
-     * @return InetAddress the socket address
+     * @return the remote address of this socket.
      */
     protected InetAddress getInetAddress() {
         return address;
     }
 
     /**
-     * Answer the socket input stream.
+     * Gets the input stream of this socket.
      * 
-     * @return InputStream an InputStream on the socket
-     * @exception IOException
-     *                thrown if an error occurs while accessing the stream
+     * @return the input stream of this socket.
+     * @throws IOException
+     *             if an error occurs while accessing the input stream.
      */
     protected abstract InputStream getInputStream() throws IOException;
 
     /**
-     * Answer the socket's localport. The field is initialized to -1 and upon
-     * demand will go to the IP stack to get the bound value. See the class
-     * comment for the context of the local port.
+     * Gets the local port number of this socket. The field is initialized to
+     * {@code -1} and upon demand will go to the IP stack to get the bound
+     * value. See the class comment for the context of the local port.
      * 
-     * @return the socket localport
+     * @return the local port number this socket is bound to.
      */
-
     protected int getLocalPort() {
         return localport;
     }
 
     /**
-     * Answer the nominated socket option.
+     * Gets the value of the given socket option.
      * 
      * @param optID
-     *            the socket option to retrieve
-     * @return Object the option value
-     * @exception SocketException
-     *                thrown if an error occurs while accessing the option
+     *            the socket option to retrieve.
+     * @return the option value.
+     * @throws SocketException
+     *             if an error occurs while accessing the option.
      */
     public abstract Object getOption(int optID) throws SocketException;
 
     /**
-     * Answer the socket output stream.
+     * Gets the output stream of this socket.
      * 
-     * @return OutputStream an OutputStream on the socket
-     * @exception IOException
-     *                thrown if an error occurs while accessing the stream
+     * @return the output stream of this socket.
+     * @throws IOException
+     *             if an error occurs while accessing the output stream.
      */
     protected abstract OutputStream getOutputStream() throws IOException;
 
     /**
-     * Answer the socket's remote port. This value is not meaningful when the
-     * socketImpl is wrapped by a ServerSocket.
+     * Gets the remote port number of this socket. This value is not meaningful
+     * when this instance is wrapped by a {@code ServerSocket}.
      * 
-     * @return the remote port the socket is connected to
+     * @return the remote port this socket is connected to.
      */
     protected int getPort() {
         return port;
     }
 
     /**
-     * Listen for connection requests on this stream socket. Incoming connection
-     * requests are queued, up to the limit nominated by backlog. Additional
-     * requests are rejected. listen() may only be invoked on stream sockets.
+     * Listens for connection requests on this streaming socket. Incoming
+     * connection requests are queued up to the limit specified by {@code
+     * backlog}. Additional requests are rejected. The method {@code listen()}
+     * may only be invoked on streaming sockets.
      * 
      * @param backlog
-     *            the max number of outstanding connection requests
-     * @exception IOException
-     *                thrown if an error occurs while listening
+     *            the maximum number of outstanding connection requests.
+     * @throws IOException
+     *             if an error occurs while listening.
      */
     protected abstract void listen(int backlog) throws IOException;
 
     /**
-     * Set the nominated socket option.
-     * 
+     * Sets the value for the specified socket option.
+     *
      * @param optID
-     *            the socket option to set
+     *            the socket option to be set.
      * @param val
-     *            the option value
-     * @exception SocketException
-     *                thrown if an error occurs while setting the option
+     *            the option value.
+     * @throws SocketException
+     *             if an error occurs while setting the option.
      */
     public abstract void setOption(int optID, Object val)
             throws SocketException;
 
     /**
-     * Answers a string containing a concise, human-readable description of the
+     * Returns a string containing a concise, human-readable description of the
      * socket.
      * 
-     * @return the description
+     * @return the textual representation of this socket.
      */
     @SuppressWarnings("nls")
     @Override
@@ -256,8 +263,8 @@
     }
 
     /**
-     * In the IP stack, write at most <code>count</code> bytes on the socket
-     * from the <code>buffer</code>, from the <code>offset</code>.
+     * In the IP stack, write at most {@code count} bytes on the socket
+     * from the {@code buffer}, from the {@code offset}.
      * 
      * @param buffer
      *            the buffer to read into
@@ -265,8 +272,8 @@
      *            the offset into the buffer
      * @param count
      *            the number of bytes to write
-     * @return the actual number of bytes written
-     * @exception IOException
+     * @return int the actual number of bytes written
+     * @throws IOException
      *                thrown if an error occurs while writing
      */
     int write(byte[] buffer, int offset, int count) throws IOException {
@@ -278,13 +285,13 @@
     }
 
     /**
-     * Shutdown the input portion of the socket.
-     * 
-     * The default implementation always throws an {@link IOException} to
+     * Closes the input channel of this socket.
+     * <p>
+     * This default implementation always throws an {@link IOException} to
      * indicate that the subclass should have overridden this method.
      * 
      * @throws IOException
-     *             Always. Designed to be subclassed.
+     *             always because this method should be overridden.
      */
     protected void shutdownInput() throws IOException {
         // KA025=Method has not been implemented
@@ -292,13 +299,13 @@
     }
 
     /**
-     * Shutdown the output portion of the socket.
-     * 
-     * The default implementation always throws an {@link IOException} to
+     * Closes the output channel of this socket.
+     * <p>
+     * This default implementation always throws an {@link IOException} to
      * indicate that the subclass should have overridden this method.
      * 
      * @throws IOException
-     *             Always. Designed to be subclassed.
+     *             always because this method should be overridden.
      */
     protected void shutdownOutput() throws IOException {
         // KA025=Method has not been implemented
@@ -306,52 +313,50 @@
     }
 
     /**
-     * Connect the socket to the host/port specified by the SocketAddress with a
-     * specified timeout.
+     * Connects this socket to the remote host address and port number specified
+     * by the {@code SocketAddress} object with the given timeout. This method
+     * will block indefinitely if the timeout is set to zero.
      * 
      * @param remoteAddr
-     *            the remote machine address and port to connect to
+     *            the remote host address and port number to connect to.
      * @param timeout
-     *            the millisecond timeout value, the connect will block
-     *            indefinitely for a zero value.
-     * 
-     * @exception IOException
-     *                if a problem occurs during the connect
+     *            the timeout value in milliseconds.
+     * @throws IOException
+     *             if an error occurs while connecting.
      */
     protected abstract void connect(SocketAddress remoteAddr, int timeout)
             throws IOException;
 
     /**
-     * Answer if the socket supports urgent data. Subclasses should override
-     * this method.
+     * Returns whether the socket supports urgent data or not. Subclasses should
+     * override this method.
      * 
-     * @return false, subclasses must override
+     * @return {@code false} because subclasses must override this method.
      */
     protected boolean supportsUrgentData() {
         return false;
     }
 
     /**
-     * Send the single byte of urgent data on the socket.
+     * Sends the single byte of urgent data on the socket.
      * 
      * @param value
-     *            the byte of urgent data
-     * 
-     * @exception IOException
-     *                when an error occurs sending urgent data
+     *            the byte of urgent data.
+     * @throws IOException
+     *             if an error occurs sending urgent data.
      */
     protected abstract void sendUrgentData(int value) throws IOException;
 
     /**
-     * Sets performance preference for connectionTime, latency and bandwidth.
+     * Sets performance preference for connection time, latency and bandwidth.
      * Does nothing by default.
      * 
      * @param connectionTime
-     *            the importance of connect time
+     *            the importance of connect time.
      * @param latency
-     *            the importance of latency
+     *            the importance of latency.
      * @param bandwidth
-     *            the importance of bandwidth
+     *            the importance of bandwidth.
      */
     protected void setPerformancePreferences(int connectionTime, int latency,
             int bandwidth) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImplFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImplFactory.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImplFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImplFactory.java Wed May  6 08:33:17 2009
@@ -18,15 +18,14 @@
 package java.net;
 
 /**
- * This interface defines a factory for socket implementations. It is used by
- * the classes <code>Socket</code> and <code>ServerSocket</code> to create
- * socket implementations.
+ * This interface defines a factory for socket implementations.
  */
 public interface SocketImplFactory {
+
     /**
-     * Creates a new <code>SocketImpl</code> instance.
+     * Creates a new {@code SocketImpl} instance.
      * 
-     * @return SocketImpl
+     * @return the created {@code SocketImpl} instance.
      */
     SocketImpl createSocketImpl();
 }



Mime
View raw message