You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/06 10:33:22 UTC
svn commit: r772095 [4/6] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
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();
}