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
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 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:
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected intThe default port the client should connect to.protected StringThe hostname used for the connection (null = no hostname supplied).protected InputStreamThe socket's InputStream.protected OutputStreamThe socket's OutputStream.protected ServerSocketFactoryThe socket's ServerSocket Factory.protected SocketThe socket used for the connection.protected SocketFactoryThe socket's SocketFactory.protected intThe timeout to use after opening a socket.protected intDefaults toDEFAULT_CONNECT_TIMEOUT.static final StringThe end of line character sequence used by most IETF protocols.protected InetSocketAddressThe remote socket address used for the connection.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionprotected voidBecause 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 the connect() methods.voidAdds a ProtocolCommandListener.protected voidApplies socket attributes.protected OutputStreamGets the non-null OutputStream or throwsNullPointerException.voidOpens a Socket connected to a remote host at the current default port and originating from the current host at a system assigned port.voidOpens a Socket connected to a remote host at the specified port and originating from the current host at a system assigned port.voidconnect(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.voidconnect(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.voidconnect(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.voidconnect(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.protected voidCreate the CommandSupport instance if requiredvoidDisconnects the socket connection.protected voidfireCommandSent(String command, String message) If there are any listeners, send them the command details.protected voidfireReplyReceived(int replyCode, String reply) If there are any listeners, send them the reply details.Gets the charset.Deprecated.Since the code now requires Java 1.6 as a minimumprotected ProtocolCommandSupportSubclasses can override this if they need to provide their own instance field for backwards compatibility.intGets the underlying socket connection timeout.intReturns the current value of the default port (stored in_defaultPort_).intReturns the default timeout in milliseconds that is used when opening a socket.booleanReturns the current value of the SO_KEEPALIVE flag on the currently opened socket.Returns the local address to which the client's socket is bound.intReturns the port number of the open socket on the local host used for the connection.getProxy()Gets the proxy for use with all the connections.protected intGets the current receivedBuffer sizeprotected InetSocketAddressGets the remote socket address used for the connection.intReturns the port number of the remote host to which the client is connected.protected intGets the current sendBuffer sizeGets the underlyingServerSocketFactoryintReturns the current SO_LINGER timeout of the currently opened socket.intReturns the timeout in milliseconds of the currently opened socket.booleanReturns true if Nagle's algorithm is enabled on the currently opened socket.booleanMake various checks on the socket to test if it is available for use.booleanReturns true if the client is currently connected to a server.voidRemoves a ProtocolCommandListener.voidsetCharset(Charset charset) Sets the charset.voidsetConnectTimeout(int connectTimeout) Sets the connection timeout in milliseconds, which will be passed to theSocketobject's connect() method.voidsetDefaultPort(int port) Sets the default port the SocketClient should connect to when a port is not specified.voidsetDefaultTimeout(int timeout) Sets the default timeout in milliseconds to use when opening a socket.voidsetKeepAlive(boolean keepAlive) Sets the SO_KEEPALIVE flag on the currently opened socket.voidSets the proxy for use with all the connections.voidsetReceiveBufferSize(int size) Sets the underlying socket receive buffer size.voidsetSendBufferSize(int size) Sets the underlying socket send buffer size.voidSets the ServerSocketFactory used by the SocketClient to open ServerSocket connections.voidsetSocketFactory(SocketFactory factory) Sets the SocketFactory used by the SocketClient to open socket connections.voidsetSoLinger(boolean on, int val) Sets the SO_LINGER timeout on the currently opened socket.voidsetSoTimeout(int timeout) Sets the timeout in milliseconds of a currently open connection.voidsetTcpNoDelay(boolean on) Enables or disables the Nagle's algorithm (TCP_NODELAY) on the currently opened socket.booleanverifyRemote(Socket socket) Verifies that the remote end of the given socket is connected to the same host that the SocketClient is currently connected to.
- 
Field Details- 
NETASCII_EOLThe end of line character sequence used by most IETF protocols. That is a carriage return followed by a newline: "\r\n"- See Also:
 
- 
_timeout_The timeout to use after opening a socket.
- 
_socket_The socket used for the connection.
- 
_hostname_The hostname used for the connection (null = no hostname supplied).
- 
remoteInetSocketAddressThe remote socket address used for the connection.
- 
_defaultPort_The default port the client should connect to.
- 
_input_The socket's InputStream.
- 
_output_The socket's OutputStream.
- 
_socketFactory_The socket's SocketFactory.
- 
_serverSocketFactory_The socket's ServerSocket Factory.
- 
connectTimeoutDefaults toDEFAULT_CONNECT_TIMEOUT.
 
- 
- 
Constructor Details- 
SocketClientpublic 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 Details- 
_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 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:
- IOException- (SocketException) if a problem occurs with the socket
 
- 
addProtocolCommandListenerAdds a ProtocolCommandListener.- Parameters:
- listener- The ProtocolCommandListener to add.
- Since:
- 3.0
 
- 
applySocketAttributesApplies socket attributes.- Throws:
- SocketException- if there is an error in the underlying protocol, such as a TCP error.
- Since:
- 3.8.0
 
- 
checkOpenOutputStreamGets the non-null OutputStream or throwsNullPointerException.This method does not allocate resources. - Returns:
- the non-null OutputStream.
- Since:
- 3.11.0
 
- 
connectOpens 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:
- 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.
 
- 
connectOpens 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:
- 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.
 
- 
connectpublic void connect(InetAddress host, int port, InetAddress localAddr, int localPort) throws SocketException, 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:
- 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.
 
- 
connectOpens 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:
- 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.
- UnknownHostException- If the hostname cannot be resolved.
 
- 
connectOpens 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:
- 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.
- UnknownHostException- If the hostname cannot be resolved.
 
- 
connectpublic void connect(String hostname, int port, InetAddress localAddr, int localPort) throws SocketException, 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:
- 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.
- UnknownHostException- If the hostname cannot be resolved.
 
- 
createCommandSupportCreate the CommandSupport instance if required
- 
disconnectDisconnects 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:
- IOException- not thrown, subclasses may throw.
 
- 
fireCommandSentIf there are any listeners, send them the command details.- Parameters:
- command- the command name
- message- the complete message, including command name
- Since:
- 3.0
 
- 
fireReplyReceivedIf there are any listeners, send them the reply details.- Parameters:
- replyCode- the code extracted from the reply
- reply- the full reply text
- Since:
- 3.0
 
- 
getCharsetGets the charset.- Returns:
- the charset.
- Since:
- 3.3
 
- 
getCharsetNameDeprecated.Since the code now requires Java 1.6 as a minimumGets the charset name.- Returns:
- the charset.
- Since:
- 3.3
 
- 
getCommandSupportSubclasses can override this if they need to provide their own instance field for backwards compatibility.- Returns:
- the CommandSupport instance, may be null
- Since:
- 3.0
 
- 
getConnectTimeoutGets the underlying socket connection timeout.- Returns:
- timeout (in ms)
- Since:
- 2.0
 
- 
getDefaultPortReturns the current value of the default port (stored in_defaultPort_).- Returns:
- The current value of the default port.
 
- 
getDefaultTimeoutReturns 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.
 
- 
getKeepAliveReturns the current value of the SO_KEEPALIVE flag on the currently opened socket. Delegates toSocket.getKeepAlive()- Returns:
- True if SO_KEEPALIVE is enabled.
- Throws:
- SocketException- if there is a problem with the socket
- NullPointerException- if the socket is not currently open
- Since:
- 2.2
 
- 
getLocalAddressReturns 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:
- NullPointerException- if the socket is not currently open
 
- 
getLocalPortReturns 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:
- NullPointerException- if the socket is not currently open
 
- 
getProxyGets the proxy for use with all the connections.- Returns:
- the current proxy for connections.
 
- 
getReceiveBufferSizeGets the current receivedBuffer size- Returns:
- the size, or -1 if not initialized
- Since:
- 3.0
 
- 
getRemoteAddress- Returns:
- The remote address to which the client is connected. Delegates to Socket.getInetAddress()
- Throws:
- NullPointerException- if the socket is not currently open
 
- 
getRemoteInetSocketAddressGets the remote socket address used for the connection.- Returns:
- the remote socket address used for the connection
- Since:
- 3.10.0
 
- 
getRemotePortReturns 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:
- NullPointerException- if the socket is not currently open
 
- 
getSendBufferSizeGets the current sendBuffer size- Returns:
- the size, or -1 if not initialized
- Since:
- 3.0
 
- 
getServerSocketFactoryGets the underlyingServerSocketFactory- Returns:
- The server socket factory
- Since:
- 2.2
 
- 
getSoLingerReturns the current SO_LINGER timeout of the currently opened socket.- Returns:
- The current SO_LINGER timeout. If SO_LINGER is disabled returns -1.
- Throws:
- SocketException- If the operation fails.
- NullPointerException- if the socket is not currently open
 
- 
getSoTimeoutReturns the timeout in milliseconds of the currently opened socket.- Returns:
- The timeout in milliseconds of the currently opened socket.
- Throws:
- SocketException- If the operation fails.
- NullPointerException- if the socket is not currently open
 
- 
getTcpNoDelayReturns 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:
- SocketException- If the operation fails.
- NullPointerException- if the socket is not currently open
 
- 
isAvailableMake 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:
- trueif the socket appears to be available for use
- Since:
- 3.0
- See Also:
 
- 
isConnectedReturns true if the client is currently connected to a server. Delegates toSocket.isConnected()- Returns:
- True if the client is currently connected to a server, false otherwise.
 
- 
removeProtocolCommandListenerRemoves a ProtocolCommandListener.- Parameters:
- listener- The ProtocolCommandListener to remove.
- Since:
- 3.0
 
- 
setCharsetSets the charset.- Parameters:
- charset- the charset.
- Since:
- 3.3
 
- 
setConnectTimeoutSets the connection timeout in milliseconds, which will be passed to theSocketobject's connect() method.- Parameters:
- connectTimeout- The connection timeout to use (in ms)
- Since:
- 2.0
 
- 
setDefaultPortSets 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.
 
- 
setDefaultTimeoutSets 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 the currently opened socket. _timeout_ contains the new timeout value.- Parameters:
- timeout- The timeout in milliseconds to use for the socket connection.
 
- 
setKeepAliveSets 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:
- SocketException- if there is a problem with the socket
- NullPointerException- if the socket is not currently open
- Since:
- 2.2
 
- 
setProxySets 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
 
- 
setReceiveBufferSizeSets the underlying socket receive buffer size.- Parameters:
- size- The size of the buffer in bytes.
- Throws:
- SocketException- never (but subclasses may wish to do so)
- Since:
- 2.0
 
- 
setSendBufferSizeSets the underlying socket send buffer size.- Parameters:
- size- The size of the buffer in bytes.
- Throws:
- SocketException- never thrown, but subclasses might want to do so
- Since:
- 2.0
 
- 
setServerSocketFactorySets 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
 
- 
setSocketFactorySets 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.
 
- 
setSoLingerSets the SO_LINGER timeout on the currently opened socket.- Parameters:
- on- True if linger is to be enabled, false if not.
- val- The- lingertimeout (in hundredths of a second?)
- Throws:
- SocketException- If the operation fails.
- NullPointerException- if the socket is not currently open
 
- 
setSoTimeoutSets 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:
- SocketException- If the operation fails.
- NullPointerException- if the socket is not currently open
 
- 
setTcpNoDelayEnables 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:
- SocketException- If the operation fails.
- NullPointerException- if the socket is not currently open
 
- 
verifyRemoteVerifies that the remote end of the given socket is connected to 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.
 
 
-