org.apache.commons.net

Class SocketClient

Known Direct Subclasses:
CharGenTCPClient, DaytimeTCPClient, DiscardTCPClient, FingerClient, NNTP, POP3, RExecClient, SMTP, TimeTCPClient

public abstract class SocketClient
extends java.lang.Object

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.
See Also:
SocketFactory

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

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.
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(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(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)
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, 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, 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
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()
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
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
setSocketFactory(SocketFactory factory)
Sets the SocketFactory used by the SocketClient to open socket connections.
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.

Field Details

NETASCII_EOL

public static final 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"

_defaultPort_

protected int _defaultPort_
The default port the client should connect to.

_input_

protected InputStream _input_
The socket's InputStream.

_isConnected_

protected boolean _isConnected_
A status variable indicating if the client's socket is currently open.

_output_

protected OutputStream _output_
The socket's OutputStream.

_socketFactory_

protected SocketFactory _socketFactory_
The socket's SocketFactory.

_socket_

protected Socket _socket_
The socket used for the connection.

_timeout_

protected int _timeout_
The timeout to use after opening a socket.

Constructor Details

SocketClient

public SocketClient()

Method Details

_connectAction_

protected void _connectAction_()
            throws IOException

connect

public void connect(InetAddress host)
            throws SocketException,
                   IOException
Parameters:
host - The remote host.

connect

public void connect(InetAddress host,
                    int port)
            throws SocketException,
                   IOException
Parameters:
host - The remote host.
port - The port to connect to on the remote host.

connect

public void connect(InetAddress host,
                    int port,
                    InetAddress localAddr,
                    int localPort)
            throws SocketException,
                   IOException
Parameters:
host - The remote host.
port - The port to connect to on the remote host.
localAddr - The local address to use.
localPort - The local port to use.

connect

public void connect(String hostname)
            throws SocketException,
                   IOException
Parameters:
hostname - The name of the remote host.

connect

public void connect(String hostname,
                    int port)
            throws SocketException,
                   IOException
Parameters:
hostname - The name of the remote host.
port - The port to connect to on the remote host.

connect

public void connect(String hostname,
                    int port,
                    InetAddress localAddr,
                    int localPort)
            throws SocketException,
                   IOException
Parameters:
hostname - The name of the remote host.
port - The port to connect to on the remote host.
localAddr - The local address to use.
localPort - The local port to use.

disconnect

public void disconnect()
            throws IOException
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.


getDefaultPort

public int getDefaultPort()
Returns:
The current value of the default port.

getDefaultTimeout

public int getDefaultTimeout()
Returns the default timeout in milliseconds that is used when opening a socket.

Returns:
The default timeout in milliseconds that is used when opening a socket.

getLocalAddress

public InetAddress getLocalAddress()
Returns the local address to which the client's socket is bound.

Returns:
The local address to which the client's socket is bound.

getLocalPort

public int getLocalPort()
Returns the port number of the open socket on the local host used for the connection.

Returns:
The port number of the open socket on the local host used for the connection.

getRemoteAddress

public InetAddress getRemoteAddress()
Returns:
The remote address to which the client is connected.

getRemotePort

public int getRemotePort()
Returns the port number of the remote host to which the client is connected.

Returns:
The port number of the remote host to which the client is connected.

getSoLinger

public int getSoLinger()
            throws SocketException
Returns the current SO_LINGER timeout of the currently opened socket.

Returns:
The current SO_LINGER timeout. If SO_LINGER is disabled returns -1.

getSoTimeout

public int getSoTimeout()
            throws SocketException
Returns the timeout in milliseconds of the currently opened socket.

Returns:
The timeout in milliseconds of the currently opened socket.

getTcpNoDelay

public boolean getTcpNoDelay()
            throws SocketException
Returns true if Nagle's algorithm is enabled on the currently opened socket.

Returns:
True if Nagle's algorithm is enabled on the currently opened socket, false otherwise.

isConnected

public boolean isConnected()
Returns true if the client is currently connected to a server.

Returns:
True if the client is currently connected to a server, false otherwise.

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:
port - The default port to set.

setDefaultTimeout

public void setDefaultTimeout(int timeout)
Parameters:
timeout - The timeout in milliseconds to use for the socket connection.

setSoLinger

public void setSoLinger(boolean on,
                        int val)
            throws SocketException
Sets the SO_LINGER timeout on the currently opened socket.

Parameters:
on - True if linger is to be enabled, false if not.
val - The linger timeout (in hundredths of a second?)

setSoTimeout

public void setSoTimeout(int timeout)
            throws SocketException
Set the timeout in milliseconds of a currently open connection. Only call this method after a connection has been opened by connect().

Parameters:
timeout - The timeout in milliseconds to use for the currently open socket connection.

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:
factory - The new SocketFactory the SocketClient should use.

setTcpNoDelay

public void setTcpNoDelay(boolean on)
            throws SocketException
Enables or disables the Nagle's algorithm (TCP_NODELAY) on the currently opened socket.

Parameters:
on - True if Nagle's algorithm is to be enabled, false if not.

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.

Returns:
True if the remote hosts are the same, false if not.