Package org.apache.commons.net
Class SocketClient
- java.lang.Object
-
- org.apache.commons.net.SocketClient
-
- Direct Known Subclasses:
CharGenTCPClient
,DaytimeTCPClient
,DiscardTCPClient
,FingerClient
,FTP
,IMAP
,NNTP
,POP3
,RExecClient
,SMTP
,TelnetClient
,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 thesetSocketFactory
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 aSocketFactory
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 instantiating 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
Fields Modifier and Type Field Description protected int
_defaultPort_
The default port the client should connect to.protected java.lang.String
_hostname_
The hostname used for the connection (null = no hostname supplied).protected java.io.InputStream
_input_
The socket's InputStream.protected java.io.OutputStream
_output_
The socket's OutputStream.protected javax.net.ServerSocketFactory
_serverSocketFactory_
The socket's ServerSocket Factory.protected java.net.Socket
_socket_
The socket used for the connection.protected javax.net.SocketFactory
_socketFactory_
The socket's SocketFactory.protected int
_timeout_
The timeout to use after opening a socket.protected int
connectTimeout
static java.lang.String
NETASCII_EOL
The end of line character sequence used by most IETF protocols.
-
Constructor Summary
Constructors Constructor Description SocketClient()
Default constructor for SocketClient.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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
addProtocolCommandListener(ProtocolCommandListener listener)
Adds a ProtocolCommandListener.void
connect(java.lang.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(java.lang.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(java.lang.String hostname, int port, java.net.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(java.net.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(java.net.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(java.net.InetAddress host, int port, java.net.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.protected void
createCommandSupport()
Create the CommandSupport instance if requiredvoid
disconnect()
Disconnects the socket connection.protected void
fireCommandSent(java.lang.String command, java.lang.String message)
If there are any listeners, send them the command details.protected void
fireReplyReceived(int replyCode, java.lang.String reply)
If there are any listeners, send them the reply details.java.nio.charset.Charset
getCharset()
Gets the charset.java.lang.String
getCharsetName()
Deprecated.Since the code now requires Java 1.6 as a mininmumprotected ProtocolCommandSupport
getCommandSupport()
Subclasses can override this if they need to provide their own instance field for backwards compatibilty.int
getConnectTimeout()
Get the underlying socket connection timeout.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.boolean
getKeepAlive()
Returns the current value of the SO_KEEPALIVE flag on the currently opened socket.java.net.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.java.net.Proxy
getProxy()
Gets the proxy for use with all the connections.protected int
getReceiveBufferSize()
Get the current receivedBuffer sizejava.net.InetAddress
getRemoteAddress()
int
getRemotePort()
Returns the port number of the remote host to which the client is connected.protected int
getSendBufferSize()
Get the current sendBuffer sizejavax.net.ServerSocketFactory
getServerSocketFactory()
Get the underlyingServerSocketFactory
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
isAvailable()
Make various checks on the socket to test if it is available for use.boolean
isConnected()
Returns true if the client is currently connected to a server.void
removeProtocolCommandListener(ProtocolCommandListener listener)
Removes a ProtocolCommandListener.void
setCharset(java.nio.charset.Charset charset)
Sets the charset.void
setConnectTimeout(int connectTimeout)
Sets the connection timeout in milliseconds, which will be passed to theSocket
object's connect() method.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
setKeepAlive(boolean keepAlive)
Sets the SO_KEEPALIVE flag on the currently opened socket.void
setProxy(java.net.Proxy proxy)
Sets the proxy for use with all the connections.void
setReceiveBufferSize(int size)
Sets the underlying socket receive buffer size.void
setSendBufferSize(int size)
Set the underlying socket send buffer size.void
setServerSocketFactory(javax.net.ServerSocketFactory factory)
Sets the ServerSocketFactory used by the SocketClient to open ServerSocket connections.void
setSocketFactory(javax.net.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(java.net.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 Detail
-
NETASCII_EOL
public static final java.lang.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"- See Also:
- Constant Field Values
-
_timeout_
protected int _timeout_
The timeout to use after opening a socket.
-
_socket_
protected java.net.Socket _socket_
The socket used for the connection.
-
_hostname_
protected java.lang.String _hostname_
The hostname used for the connection (null = no hostname supplied).
-
_defaultPort_
protected int _defaultPort_
The default port the client should connect to.
-
_input_
protected java.io.InputStream _input_
The socket's InputStream.
-
_output_
protected java.io.OutputStream _output_
The socket's OutputStream.
-
_socketFactory_
protected javax.net.SocketFactory _socketFactory_
The socket's SocketFactory.
-
_serverSocketFactory_
protected javax.net.ServerSocketFactory _serverSocketFactory_
The socket's ServerSocket Factory.
-
connectTimeout
protected int connectTimeout
-
-
Constructor Detail
-
SocketClient
public SocketClient()
Default constructor for SocketClient. Initializes _socket_ to null, _timeout_ to 0, _defaultPort to 0, _isConnected_ to false, charset toCharset.defaultCharset()
and _socketFactory_ to a shared instance ofDefaultSocketFactory
.
-
-
Method Detail
-
_connectAction_
protected void _connectAction_() throws java.io.IOException
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.- Throws:
java.io.IOException
- (SocketException) if a problem occurs with the socket
-
connect
public void connect(java.net.InetAddress host, int port) throws java.net.SocketException, java.io.IOException
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:
host
- The remote host.port
- The port to connect to on the remote host.- Throws:
java.net.SocketException
- If the socket timeout could not be set.java.io.IOException
- If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
-
connect
public void connect(java.lang.String hostname, int port) throws java.net.SocketException, java.io.IOException
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:
hostname
- The name of the remote host.port
- The port to connect to on the remote host.- Throws:
java.net.SocketException
- If the socket timeout could not be set.java.io.IOException
- If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.java.net.UnknownHostException
- If the hostname cannot be resolved.
-
connect
public void connect(java.net.InetAddress host, int port, java.net.InetAddress localAddr, int localPort) throws java.net.SocketException, java.io.IOException
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:
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.- Throws:
java.net.SocketException
- If the socket timeout could not be set.java.io.IOException
- If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
-
connect
public void connect(java.lang.String hostname, int port, java.net.InetAddress localAddr, int localPort) throws java.net.SocketException, java.io.IOException
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:
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.- Throws:
java.net.SocketException
- If the socket timeout could not be set.java.io.IOException
- If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.java.net.UnknownHostException
- If the hostname cannot be resolved.
-
connect
public void connect(java.net.InetAddress host) throws java.net.SocketException, java.io.IOException
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:
host
- The remote host.- Throws:
java.net.SocketException
- If the socket timeout could not be set.java.io.IOException
- If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.
-
connect
public void connect(java.lang.String hostname) throws java.net.SocketException, java.io.IOException
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:
hostname
- The name of the remote host.- Throws:
java.net.SocketException
- If the socket timeout could not be set.java.io.IOException
- If the socket could not be opened. In most cases you will only want to catch IOException since SocketException is derived from it.java.net.UnknownHostException
- If the hostname cannot be resolved.
-
disconnect
public void disconnect() throws java.io.IOException
Disconnects the socket connection. You should call this method after you've finished using the class instance and also before you callconnect()
again. _isConnected_ is set to false, _socket_ is set to null, _input_ is set to null, and _output_ is set to null.- Throws:
java.io.IOException
- If there is an error closing the socket.
-
isConnected
public boolean isConnected()
Returns true if the client is currently connected to a server.Delegates to
Socket.isConnected()
- Returns:
- True if the client is currently connected to a server, false otherwise.
-
isAvailable
public boolean isAvailable()
Make various checks on the socket to test if it is available for use. Note that the only sure test is to use it, but these checks may help in some cases.- Returns:
true
if the socket appears to be available for use- Since:
- 3.0
- See Also:
- NET-350
-
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.
-
getDefaultPort
public int getDefaultPort()
Returns the current value of the default port (stored in_defaultPort_
).- Returns:
- The current value of the default port.
-
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 toconnect()
and should not be confused withsetSoTimeout()
which operates on an the currently opened socket. _timeout_ contains the new timeout value.- Parameters:
timeout
- The timeout in milliseconds to use for the socket connection.
-
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.
-
setSoTimeout
public void setSoTimeout(int timeout) throws java.net.SocketException
Set the timeout in milliseconds of a currently open connection. Only call this method after a connection has been opened byconnect()
.To set the initial timeout, use
setDefaultTimeout(int)
instead.- Parameters:
timeout
- The timeout in milliseconds to use for the currently open socket connection.- Throws:
java.net.SocketException
- If the operation fails.java.lang.NullPointerException
- if the socket is not currently open
-
setSendBufferSize
public void setSendBufferSize(int size) throws java.net.SocketException
Set the underlying socket send buffer size.- Parameters:
size
- The size of the buffer in bytes.- Throws:
java.net.SocketException
- never thrown, but subclasses might want to do so- Since:
- 2.0
-
getSendBufferSize
protected int getSendBufferSize()
Get the current sendBuffer size- Returns:
- the size, or -1 if not initialised
- Since:
- 3.0
-
setReceiveBufferSize
public void setReceiveBufferSize(int size) throws java.net.SocketException
Sets the underlying socket receive buffer size.- Parameters:
size
- The size of the buffer in bytes.- Throws:
java.net.SocketException
- never (but subclasses may wish to do so)- Since:
- 2.0
-
getReceiveBufferSize
protected int getReceiveBufferSize()
Get the current receivedBuffer size- Returns:
- the size, or -1 if not initialised
- Since:
- 3.0
-
getSoTimeout
public int getSoTimeout() throws java.net.SocketException
Returns the timeout in milliseconds of the currently opened socket.- Returns:
- The timeout in milliseconds of the currently opened socket.
- Throws:
java.net.SocketException
- If the operation fails.java.lang.NullPointerException
- if the socket is not currently open
-
setTcpNoDelay
public void setTcpNoDelay(boolean on) throws java.net.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.- Throws:
java.net.SocketException
- If the operation fails.java.lang.NullPointerException
- if the socket is not currently open
-
getTcpNoDelay
public boolean getTcpNoDelay() throws java.net.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.
- Throws:
java.net.SocketException
- If the operation fails.java.lang.NullPointerException
- if the socket is not currently open
-
setKeepAlive
public void setKeepAlive(boolean keepAlive) throws java.net.SocketException
Sets the SO_KEEPALIVE flag on the currently opened socket. From the Javadocs, the default keepalive time is 2 hours (although this is implementation dependent). It looks as though the Windows WSA sockets implementation allows a specific keepalive value to be set, although this seems not to be the case on other systems.- Parameters:
keepAlive
- If true, keepAlive is turned on- Throws:
java.net.SocketException
- if there is a problem with the socketjava.lang.NullPointerException
- if the socket is not currently open- Since:
- 2.2
-
getKeepAlive
public boolean getKeepAlive() throws java.net.SocketException
Returns the current value of the SO_KEEPALIVE flag on the currently opened socket. Delegates toSocket.getKeepAlive()
- Returns:
- True if SO_KEEPALIVE is enabled.
- Throws:
java.net.SocketException
- if there is a problem with the socketjava.lang.NullPointerException
- if the socket is not currently open- Since:
- 2.2
-
setSoLinger
public void setSoLinger(boolean on, int val) throws java.net.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?)- Throws:
java.net.SocketException
- If the operation fails.java.lang.NullPointerException
- if the socket is not currently open
-
getSoLinger
public int getSoLinger() throws java.net.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.
- Throws:
java.net.SocketException
- If the operation fails.java.lang.NullPointerException
- if the socket is not currently open
-
getLocalPort
public int getLocalPort()
Returns the port number of the open socket on the local host used for the connection. Delegates toSocket.getLocalPort()
- Returns:
- The port number of the open socket on the local host used for the connection.
- Throws:
java.lang.NullPointerException
- if the socket is not currently open
-
getLocalAddress
public java.net.InetAddress getLocalAddress()
Returns the local address to which the client's socket is bound. Delegates toSocket.getLocalAddress()
- Returns:
- The local address to which the client's socket is bound.
- Throws:
java.lang.NullPointerException
- if the socket is not currently open
-
getRemotePort
public int getRemotePort()
Returns the port number of the remote host to which the client is connected. Delegates toSocket.getPort()
- Returns:
- The port number of the remote host to which the client is connected.
- Throws:
java.lang.NullPointerException
- if the socket is not currently open
-
getRemoteAddress
public java.net.InetAddress getRemoteAddress()
- Returns:
- The remote address to which the client is connected.
Delegates to
Socket.getInetAddress()
- Throws:
java.lang.NullPointerException
- if the socket is not currently open
-
verifyRemote
public boolean verifyRemote(java.net.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:
socket
- the item to check against- Returns:
- True if the remote hosts are the same, false if not.
-
setSocketFactory
public void setSocketFactory(javax.net.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). Any proxy setting is discarded.- Parameters:
factory
- The new SocketFactory the SocketClient should use.
-
setServerSocketFactory
public void setServerSocketFactory(javax.net.ServerSocketFactory factory)
Sets the ServerSocketFactory used by the SocketClient to open ServerSocket 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 ServerSocketFactory the SocketClient should use.- Since:
- 2.0
-
setConnectTimeout
public void setConnectTimeout(int connectTimeout)
Sets the connection timeout in milliseconds, which will be passed to theSocket
object's connect() method.- Parameters:
connectTimeout
- The connection timeout to use (in ms)- Since:
- 2.0
-
getConnectTimeout
public int getConnectTimeout()
Get the underlying socket connection timeout.- Returns:
- timeout (in ms)
- Since:
- 2.0
-
getServerSocketFactory
public javax.net.ServerSocketFactory getServerSocketFactory()
Get the underlyingServerSocketFactory
- Returns:
- The server socket factory
- Since:
- 2.2
-
addProtocolCommandListener
public void addProtocolCommandListener(ProtocolCommandListener listener)
Adds a ProtocolCommandListener.- Parameters:
listener
- The ProtocolCommandListener to add.- Since:
- 3.0
-
removeProtocolCommandListener
public void removeProtocolCommandListener(ProtocolCommandListener listener)
Removes a ProtocolCommandListener.- Parameters:
listener
- The ProtocolCommandListener to remove.- Since:
- 3.0
-
fireReplyReceived
protected void fireReplyReceived(int replyCode, java.lang.String reply)
If there are any listeners, send them the reply details.- Parameters:
replyCode
- the code extracted from the replyreply
- the full reply text- Since:
- 3.0
-
fireCommandSent
protected void fireCommandSent(java.lang.String command, java.lang.String message)
If there are any listeners, send them the command details.- Parameters:
command
- the command namemessage
- the complete message, including command name- Since:
- 3.0
-
createCommandSupport
protected void createCommandSupport()
Create the CommandSupport instance if required
-
getCommandSupport
protected ProtocolCommandSupport getCommandSupport()
Subclasses can override this if they need to provide their own instance field for backwards compatibilty.- Returns:
- the CommandSupport instance, may be
null
- Since:
- 3.0
-
setProxy
public void setProxy(java.net.Proxy proxy)
Sets the proxy for use with all the connections. The proxy is used for connections established after the call to this method.- Parameters:
proxy
- the new proxy for connections.- Since:
- 3.2
-
getProxy
public java.net.Proxy getProxy()
Gets the proxy for use with all the connections.- Returns:
- the current proxy for connections.
-
getCharsetName
@Deprecated public java.lang.String getCharsetName()
Deprecated.Since the code now requires Java 1.6 as a mininmumGets the charset name.- Returns:
- the charset.
- Since:
- 3.3
-
getCharset
public java.nio.charset.Charset getCharset()
Gets the charset.- Returns:
- the charset.
- Since:
- 3.3
-
setCharset
public void setCharset(java.nio.charset.Charset charset)
Sets the charset.- Parameters:
charset
- the charset.- Since:
- 3.3
-
-