org.apache.commons.net
Class SocketClient

public class SocketClient
The SocketClient provides the basic operations that are required of client objects accessing sockets. It is meant to be subclassed to avoid having to rewrite the same code over and over again to open a socket, close a socket, set timeouts, etc. Of special note is the setSocketFactory method, which allows you to control the type of Socket the SocketClient creates for initiating network connections. This is especially useful for adding SSL or proxy support as well as better support for applets. For example, you could create a SocketFactory that requests browser security capabilities before creating a socket. All classes derived from SocketClient should use the _socketFactory_ member variable to create Socket and ServerSocket instances rather than instanting them by directly invoking a constructor. By honoring this contract you guarantee that a user will always be able to provide his own Socket implementations by substituting his own SocketFactory.
SinceNot specified.
VersionNot specified.
AuthorDaniel F. Savarese
See also
Wiki javadoc Use textile entry format.
Add your comments here.
Field Summary
static String NETASCII_EOL
The end of line character sequence used by most IETF protocols.
protected int _defaultPort_
The default port the client should connect to.
protected InputStream _input_
The socket's InputStream.
protected boolean _isConnected_
A status variable indicating if the client's socket is currently open.
protected OutputStream _output_
The socket's OutputStream.
protected SocketFactory _socketFactory_
The socket's SocketFactory.
protected Socket _socket_
The socket used for the connection.
protected int _timeout_
The timeout to use after opening a socket.
Constructor Summary
SocketClient()
Default constructor for SocketClient.
Method Summary
void connect( InetAddress host, int port )
Opens a Socket connected to a remote host at the specified port and originating from the current host at a system assigned port.
void connect( String hostname, int port )
Opens a Socket connected to a remote host at the specified port and originating from the current host at a system assigned port.
void connect( InetAddress host, int port, InetAddress localAddr, int localPort )
Opens a Socket connected to a remote host at the specified port and originating from the specified local address and port.
void connect( String hostname, int port, InetAddress localAddr, int localPort )
Opens a Socket connected to a remote host at the specified port and originating from the specified local address and port.
void connect( InetAddress host )
Opens a Socket connected to a remote host at the current default port and originating from the current host at a system assigned port.
void connect( String hostname )
Opens a Socket connected to a remote host at the current default port and originating from the current host at a system assigned port.
void disconnect()
Disconnects the socket connection.
int getDefaultPort()
Returns the current value of the default port (stored in _defaultPort_ ).
int getDefaultTimeout()
Returns the default timeout in milliseconds that is used when opening a socket.
InetAddress getLocalAddress()
Returns the local address to which the client's socket is bound.
int getLocalPort()
Returns the port number of the open socket on the local host used for the connection.
InetAddress getRemoteAddress()
No description provided.
int getRemotePort()
Returns the port number of the remote host to which the client is connected.
int getSoLinger()
Returns the current SO_LINGER timeout of the currently opened socket.
int getSoTimeout()
Returns the timeout in milliseconds of the currently opened socket.
boolean getTcpNoDelay()
Returns true if Nagle's algorithm is enabled on the currently opened socket.
boolean isConnected()
Returns true if the client is currently connected to a server.
void setDefaultPort( int port )
Sets the default port the SocketClient should connect to when a port is not specified.
void setDefaultTimeout( int timeout )
Set the default timeout in milliseconds to use when opening a socket.
void setSocketFactory( SocketFactory factory )
Sets the SocketFactory used by the SocketClient to open socket connections.
void setSoLinger( boolean on, int val )
Sets the SO_LINGER timeout on the currently opened socket.
void setSoTimeout( int timeout )
Set the timeout in milliseconds of a currently open connection.
void setTcpNoDelay( boolean on )
Enables or disables the Nagle's algorithm (TCP_NODELAY) on the currently opened socket.
boolean verifyRemote( Socket socket )
Verifies that the remote end of the given socket is connected to the the same host that the SocketClient is currently connected to.
protected void _connectAction_()
Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all of the connect() methods.
NETASCII_EOL
public static String NETASCII_EOL
The end of line character sequence used by most IETF protocols. That is a carriage return followed by a newline: "\r\n"
Wiki javadoc Use textile entry format.
Add your comments here.
_defaultPort_
protected int _defaultPort_
The default port the client should connect to.
Wiki javadoc Use textile entry format.
Add your comments here.
_input_
protected InputStream _input_
The socket's InputStream.
Wiki javadoc Use textile entry format.
Add your comments here.
_isConnected_
protected boolean _isConnected_
A status variable indicating if the client's socket is currently open.
Wiki javadoc Use textile entry format.
Add your comments here.
_output_
protected OutputStream _output_
The socket's OutputStream.
Wiki javadoc Use textile entry format.
Add your comments here.
_socketFactory_
protected SocketFactory _socketFactory_
The socket's SocketFactory.
Wiki javadoc Use textile entry format.
Add your comments here.
_socket_
protected Socket _socket_
The socket used for the connection.
Wiki javadoc Use textile entry format.
Add your comments here.
_timeout_
protected int _timeout_
The timeout to use after opening a socket.
Wiki javadoc Use textile entry format.
Add your comments here.
SocketClient
public SocketClient ( )
Default constructor for SocketClient. Initializes _socket_ to null, _timeout_ to 0, _defaultPort to 0, _isConnected_ to false, and _socketFactory_ to a shared instance of DefaultSocketFactory .
Wiki javadoc Use textile entry format.
Add your comments here.
connect
public void connect ( InetAddress host, int port )
Opens a Socket connected to a remote host at the specified port and originating from the current host at a system assigned port. Before returning, _connectAction_() is called to perform connection initialization actions.

Parameters
TypeNameDescription
InetAddress host The remote host.
int port The port to connect to on the remote host.
Returns void No description provided.
Exceptions
SocketException If the socket timeout could not be set.
IOException If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
Wiki javadoc Use textile entry format.
Add your comments here.
connect
public void connect ( String hostname, int port )
Opens a Socket connected to a remote host at the specified port and originating from the current host at a system assigned port. Before returning, _connectAction_() is called to perform connection initialization actions.

Parameters
TypeNameDescription
String hostname The name of the remote host.
int port The port to connect to on the remote host.
Returns void No description provided.
Exceptions
SocketException If the socket timeout could not be set.
IOException If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
Wiki javadoc Use textile entry format.
Add your comments here.
connect
public void connect ( InetAddress host, int port, InetAddress localAddr, int localPort )
Opens a Socket connected to a remote host at the specified port and originating from the specified local address and port. Before returning, _connectAction_() is called to perform connection initialization actions.

Parameters
TypeNameDescription
InetAddress host The remote host.
int port The port to connect to on the remote host.
InetAddress localAddr The local address to use.
int localPort The local port to use.
Returns void No description provided.
Exceptions
SocketException If the socket timeout could not be set.
IOException If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
Wiki javadoc Use textile entry format.
Add your comments here.
connect
public void connect ( String hostname, int port, InetAddress localAddr, int localPort )
Opens a Socket connected to a remote host at the specified port and originating from the specified local address and port. Before returning, _connectAction_() is called to perform connection initialization actions.

Parameters
TypeNameDescription
String hostname The name of the remote host.
int port The port to connect to on the remote host.
InetAddress localAddr The local address to use.
int localPort The local port to use.
Returns void No description provided.
Exceptions
SocketException If the socket timeout could not be set.
IOException If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
Wiki javadoc Use textile entry format.
Add your comments here.
connect
public void connect ( InetAddress host )
Opens a Socket connected to a remote host at the current default port and originating from the current host at a system assigned port. Before returning, _connectAction_() is called to perform connection initialization actions.

Parameters
TypeNameDescription
InetAddress host The remote host.
Returns void No description provided.
Exceptions
SocketException If the socket timeout could not be set.
IOException If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
Wiki javadoc Use textile entry format.
Add your comments here.
connect
public void connect ( String hostname )
Opens a Socket connected to a remote host at the current default port and originating from the current host at a system assigned port. Before returning, _connectAction_() is called to perform connection initialization actions.

Parameters
TypeNameDescription
String hostname The name of the remote host.
Returns void No description provided.
Exceptions
SocketException If the socket timeout could not be set.
IOException If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
Wiki javadoc Use textile entry format.
Add your comments here.
disconnect
public void disconnect ( )
throws
Disconnects the socket connection. You should call this method after you've finished using the class instance and also before you call connect() again. _isConnected_ is set to false, _socket_ is set to null, _input_ is set to null, and _output_ is set to null.

Returns void No description provided.
Exceptions
IOException If there is an error closing the socket.
Wiki javadoc Use textile entry format.
Add your comments here.
getDefaultPort
public int getDefaultPort ( )
Returns the current value of the default port (stored in _defaultPort_ ).

Wiki javadoc Use textile entry format.
Add your comments here.
getDefaultTimeout
public int getDefaultTimeout ( )
Returns the default timeout in milliseconds that is used when opening a socket.

Wiki javadoc Use textile entry format.
Add your comments here.
getLocalAddress
public InetAddress getLocalAddress ( )
Returns the local address to which the client's socket is bound.

Wiki javadoc Use textile entry format.
Add your comments here.
getLocalPort
public int getLocalPort ( )
Returns the port number of the open socket on the local host used for the connection.

Wiki javadoc Use textile entry format.
Add your comments here.
getRemoteAddress
public InetAddress getRemoteAddress ( )
No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
getRemotePort
public int getRemotePort ( )
Returns the port number of the remote host to which the client is connected.

Wiki javadoc Use textile entry format.
Add your comments here.
getSoLinger
public int getSoLinger ( )
Returns the current SO_LINGER timeout of the currently opened socket.

Exceptions
SocketException If the operation fails.
Wiki javadoc Use textile entry format.
Add your comments here.
getSoTimeout
public int getSoTimeout ( )
Returns the timeout in milliseconds of the currently opened socket.

Exceptions
SocketException If the operation fails.
Wiki javadoc Use textile entry format.
Add your comments here.
getTcpNoDelay
public boolean getTcpNoDelay ( )
Returns true if Nagle's algorithm is enabled on the currently opened socket.

Exceptions
SocketException If the operation fails.
Wiki javadoc Use textile entry format.
Add your comments here.
isConnected
public boolean isConnected ( )
Returns true if the client is currently connected to a server.

Wiki javadoc Use textile entry format.
Add your comments here.
setDefaultPort
public void setDefaultPort ( int port )
Sets the default port the SocketClient should connect to when a port is not specified. The _defaultPort_ variable stores this value. If never set, the default port is equal to zero.

Parameters
TypeNameDescription
int port The default port to set.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setDefaultTimeout
public void setDefaultTimeout ( int timeout )
Set the default timeout in milliseconds to use when opening a socket. This value is only used previous to a call to connect() and should not be confused with setSoTimeout() which operates on an the currently opened socket. _timeout_ contains the new timeout value.

Parameters
TypeNameDescription
int timeout The timeout in milliseconds to use for the socket connection.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setSocketFactory
public void setSocketFactory ( SocketFactory factory )
Sets the SocketFactory used by the SocketClient to open socket connections. If the factory value is null, then a default factory is used (only do this to reset the factory after having previously altered it).

Parameters
TypeNameDescription
SocketFactory factory The new SocketFactory the SocketClient should use.
Returns void No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
setSoLinger
public void setSoLinger ( boolean on, int val )
Sets the SO_LINGER timeout on the currently opened socket.

Parameters
TypeNameDescription
boolean on True if linger is to be enabled, false if not.
int val The linger timeout (in hundredths of a second?)
Returns void No description provided.
Exceptions
SocketException If the operation fails.
Wiki javadoc Use textile entry format.
Add your comments here.
setSoTimeout
public void setSoTimeout ( int timeout )
Set the timeout in milliseconds of a currently open connection. Only call this method after a connection has been opened by connect() .

Parameters
TypeNameDescription
int timeout The timeout in milliseconds to use for the currently open socket connection.
Returns void No description provided.
Exceptions
SocketException If the operation fails.
Wiki javadoc Use textile entry format.
Add your comments here.
setTcpNoDelay
public void setTcpNoDelay ( boolean on )
Enables or disables the Nagle's algorithm (TCP_NODELAY) on the currently opened socket.

Parameters
TypeNameDescription
boolean on True if Nagle's algorithm is to be enabled, false if not.
Returns void No description provided.
Exceptions
SocketException If the operation fails.
Wiki javadoc Use textile entry format.
Add your comments here.
verifyRemote
public boolean verifyRemote ( Socket socket )
Verifies that the remote end of the given socket is connected to the the same host that the SocketClient is currently connected to. This is useful for doing a quick security check when a client needs to accept a connection from a server, such as an FTP data connection or a BSD R command standard error stream.

Parameters
TypeNameDescription
Socket socket No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.
_connectAction_
protected void _connectAction_ ( )
throws
Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all of the connect() methods. The last action performed by every connect() method after opening a socket is to call this method.

This method sets the timeout on the just opened socket to the default timeout set by setDefaultTimeout() , sets _input_ and _output_ to the socket's InputStream and OutputStream respectively, and sets _isConnected_ to true.

Subclasses overriding this method should start by calling super._connectAction_() first to ensure the initialization of the aforementioned protected variables.

Returns void No description provided.
Exceptions
IOException No description provided.
Wiki javadoc Use textile entry format.
Add your comments here.