%line	%branch
org.apache.commons.net.SocketClient	52%	96%

1		/*
2		* Copyright 2001-2005 The Apache Software Foundation
3		*
4		* Licensed under the Apache License, Version 2.0 (the "License");
5		* you may not use this file except in compliance with the License.
6		* You may obtain a copy of the License at
7		*
8		* http://www.apache.org/licenses/LICENSE-2.0
9		*
10		* Unless required by applicable law or agreed to in writing, software
11		* distributed under the License is distributed on an "AS IS" BASIS,
12		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13		* See the License for the specific language governing permissions and
14		* limitations under the License.
15		*/
16		package org.apache.commons.net;
17
18		import java.io.IOException;
19		import java.io.InputStream;
20		import java.io.OutputStream;
21		import java.net.InetAddress;
22		import java.net.Socket;
23		import java.net.SocketException;
24
25		/**
26		* The SocketClient provides the basic operations that are required of
27		* client objects accessing sockets. It is meant to be
28		* subclassed to avoid having to rewrite the same code over and over again
29		* to open a socket, close a socket, set timeouts, etc. Of special note
30		* is the {@link #setSocketFactory setSocketFactory }
31		* method, which allows you to control the type of Socket the SocketClient
32		* creates for initiating network connections. This is especially useful
33		* for adding SSL or proxy support as well as better support for applets. For
34		* example, you could create a
35		* {@link org.apache.commons.net.SocketFactory} that
36		* requests browser security capabilities before creating a socket.
37		* All classes derived from SocketClient should use the
38		* {@link #_socketFactory_ _socketFactory_ } member variable to
39		* create Socket and ServerSocket instances rather than instanting
40		* them by directly invoking a constructor. By honoring this contract
41		* you guarantee that a user will always be able to provide his own
42		* Socket implementations by substituting his own SocketFactory.
43		* @author Daniel F. Savarese
44		* @see SocketFactory
45		*/
46		public abstract class SocketClient
47		{
48		/**
49		* The end of line character sequence used by most IETF protocols. That
50		* is a carriage return followed by a newline: "\r\n"
51		*/
52		public static final String NETASCII_EOL = "\r\n";
53
54		/** The default SocketFactory shared by all SocketClient instances. */
55	4	private static final SocketFactory __DEFAULT_SOCKET_FACTORY =
56		new DefaultSocketFactory();
57
58		/** The timeout to use after opening a socket. */
59		protected int _timeout_;
60
61		/** The socket used for the connection. */
62		protected Socket _socket_;
63
64		/**
65		* A status variable indicating if the client's socket is currently open.
66		*/
67		protected boolean _isConnected_;
68
69		/** The default port the client should connect to. */
70		protected int _defaultPort_;
71
72		/** The socket's InputStream. */
73		protected InputStream _input_;
74
75		/** The socket's OutputStream. */
76		protected OutputStream _output_;
77
78		/** The socket's SocketFactory. */
79		protected SocketFactory _socketFactory_;
80
81
82		/**
83		* Default constructor for SocketClient. Initializes
84		* _socket_ to null, _timeout_ to 0, _defaultPort to 0,
85		* _isConnected_ to false, and _socketFactory_ to a shared instance of
86		* {@link org.apache.commons.net.DefaultSocketFactory}.
87		*/
88		public SocketClient()
89	66	{
90	66	_socket_ = null;
91	66	_input_ = null;
92	66	_output_ = null;
93	66	_timeout_ = 0;
94	66	_defaultPort_ = 0;
95	66	_isConnected_ = false;
96	66	_socketFactory_ = __DEFAULT_SOCKET_FACTORY;
97	66	}
98
99
100		/**
101		* Because there are so many connect() methods, the _connectAction_()
102		* method is provided as a means of performing some action immediately
103		* after establishing a connection, rather than reimplementing all
104		* of the connect() methods. The last action performed by every
105		* connect() method after opening a socket is to call this method.
106		* <p>
107		* This method sets the timeout on the just opened socket to the default
108		* timeout set by {@link #setDefaultTimeout setDefaultTimeout() },
109		* sets _input_ and _output_ to the socket's InputStream and OutputStream
110		* respectively, and sets _isConnected_ to true.
111		* <p>
112		* Subclasses overriding this method should start by calling
113		* <code> super._connectAction_() </code> first to ensure the
114		* initialization of the aforementioned protected variables.
115		*/
116		protected void _connectAction_() throws IOException
117		{
118	68	_socket_.setSoTimeout(_timeout_);
119	68	_input_ = _socket_.getInputStream();
120	68	_output_ = _socket_.getOutputStream();
121	68	_isConnected_ = true;
122	68	}
123
124
125		/**
126		* Opens a Socket connected to a remote host at the specified port and
127		* originating from the current host at a system assigned port.
128		* Before returning, {@link #_connectAction_ _connectAction_() }
129		* is called to perform connection initialization actions.
130		* <p>
131		* @param host The remote host.
132		* @param port The port to connect to on the remote host.
133		* @exception SocketException If the socket timeout could not be set.
134		* @exception IOException If the socket could not be opened. In most
135		* cases you will only want to catch IOException since SocketException is
136		* derived from it.
137		*/
138		public void connect(InetAddress host, int port)
139		throws SocketException, IOException
140		{
141	4	_socket_ = _socketFactory_.createSocket(host, port);
142	4	_connectAction_();
143	4	}
144
145		/**
146		* Opens a Socket connected to a remote host at the specified port and
147		* originating from the current host at a system assigned port.
148		* Before returning, {@link #_connectAction_ _connectAction_() }
149		* is called to perform connection initialization actions.
150		* <p>
151		* @param hostname The name of the remote host.
152		* @param port The port to connect to on the remote host.
153		* @exception SocketException If the socket timeout could not be set.
154		* @exception IOException If the socket could not be opened. In most
155		* cases you will only want to catch IOException since SocketException is
156		* derived from it.
157		* @exception UnknownHostException If the hostname cannot be resolved.
158		*/
159		public void connect(String hostname, int port)
160		throws SocketException, IOException
161		{
162	64	_socket_ = _socketFactory_.createSocket(hostname, port);
163	64	_connectAction_();
164	64	}
165
166
167		/**
168		* Opens a Socket connected to a remote host at the specified port and
169		* originating from the specified local address and port.
170		* Before returning, {@link #_connectAction_ _connectAction_() }
171		* is called to perform connection initialization actions.
172		* <p>
173		* @param host The remote host.
174		* @param port The port to connect to on the remote host.
175		* @param localAddr The local address to use.
176		* @param localPort The local port to use.
177		* @exception SocketException If the socket timeout could not be set.
178		* @exception IOException If the socket could not be opened. In most
179		* cases you will only want to catch IOException since SocketException is
180		* derived from it.
181		*/
182		public void connect(InetAddress host, int port,
183		InetAddress localAddr, int localPort)
184		throws SocketException, IOException
185		{
186	0	_socket_ = _socketFactory_.createSocket(host, port, localAddr, localPort);
187	0	_connectAction_();
188	0	}
189
190
191		/**
192		* Opens a Socket connected to a remote host at the specified port and
193		* originating from the specified local address and port.
194		* Before returning, {@link #_connectAction_ _connectAction_() }
195		* is called to perform connection initialization actions.
196		* <p>
197		* @param hostname The name of the remote host.
198		* @param port The port to connect to on the remote host.
199		* @param localAddr The local address to use.
200		* @param localPort The local port to use.
201		* @exception SocketException If the socket timeout could not be set.
202		* @exception IOException If the socket could not be opened. In most
203		* cases you will only want to catch IOException since SocketException is
204		* derived from it.
205		* @exception UnknownHostException If the hostname cannot be resolved.
206		*/
207		public void connect(String hostname, int port,
208		InetAddress localAddr, int localPort)
209		throws SocketException, IOException
210		{
211	0	_socket_ =
212		_socketFactory_.createSocket(hostname, port, localAddr, localPort);
213	0	_connectAction_();
214	0	}
215
216
217		/**
218		* Opens a Socket connected to a remote host at the current default port
219		* and originating from the current host at a system assigned port.
220		* Before returning, {@link #_connectAction_ _connectAction_() }
221		* is called to perform connection initialization actions.
222		* <p>
223		* @param host The remote host.
224		* @exception SocketException If the socket timeout could not be set.
225		* @exception IOException If the socket could not be opened. In most
226		* cases you will only want to catch IOException since SocketException is
227		* derived from it.
228		*/
229		public void connect(InetAddress host) throws SocketException, IOException
230		{
231	0	connect(host, _defaultPort_);
232	0	}
233
234
235		/**
236		* Opens a Socket connected to a remote host at the current default
237		* port and originating from the current host at a system assigned port.
238		* Before returning, {@link #_connectAction_ _connectAction_() }
239		* is called to perform connection initialization actions.
240		* <p>
241		* @param hostname The name of the remote host.
242		* @exception SocketException If the socket timeout could not be set.
243		* @exception IOException If the socket could not be opened. In most
244		* cases you will only want to catch IOException since SocketException is
245		* derived from it.
246		* @exception UnknownHostException If the hostname cannot be resolved.
247		*/
248		public void connect(String hostname) throws SocketException, IOException
249		{
250	0	connect(hostname, _defaultPort_);
251	0	}
252
253
254		/**
255		* Disconnects the socket connection.
256		* You should call this method after you've finished using the class
257		* instance and also before you call
258		* {@link #connect connect() }
259		* again. _isConnected_ is set to false, _socket_ is set to null,
260		* _input_ is set to null, and _output_ is set to null.
261		* <p>
262		* @exception IOException If there is an error closing the socket.
263		*/
264		public void disconnect() throws IOException
265		{
266	68	_socket_.close();
267	68	_input_.close();
268	68	_output_.close();
269	68	_socket_ = null;
270	68	_input_ = null;
271	68	_output_ = null;
272	68	_isConnected_ = false;
273	68	}
274
275
276		/**
277		* Returns true if the client is currently connected to a server.
278		* <p>
279		* @return True if the client is currently connected to a server,
280		* false otherwise.
281		*/
282		public boolean isConnected()
283		{
284	48	return _isConnected_;
285		}
286
287
288		/**
289		* Sets the default port the SocketClient should connect to when a port
290		* is not specified. The {@link #_defaultPort_ _defaultPort_ }
291		* variable stores this value. If never set, the default port is equal
292		* to zero.
293		* <p>
294		* @param port The default port to set.
295		*/
296		public void setDefaultPort(int port)
297		{
298	66	_defaultPort_ = port;
299	66	}
300
301		/**
302		* Returns the current value of the default port (stored in
303		* {@link #_defaultPort_ _defaultPort_ }).
304		* <p>
305		* @return The current value of the default port.
306		*/
307		public int getDefaultPort()
308		{
309	0	return _defaultPort_;
310		}
311
312
313		/**
314		* Set the default timeout in milliseconds to use when opening a socket.
315		* This value is only used previous to a call to
316		* {@link #connect connect()}
317		* and should not be confused with {@link #setSoTimeout setSoTimeout()}
318		* which operates on an the currently opened socket. _timeout_ contains
319		* the new timeout value.
320		* <p>
321		* @param timeout The timeout in milliseconds to use for the socket
322		* connection.
323		*/
324		public void setDefaultTimeout(int timeout)
325		{
326	4	_timeout_ = timeout;
327	4	}
328
329
330		/**
331		* Returns the default timeout in milliseconds that is used when
332		* opening a socket.
333		* <p>
334		* @return The default timeout in milliseconds that is used when
335		* opening a socket.
336		*/
337		public int getDefaultTimeout()
338		{
339	0	return _timeout_;
340		}
341
342
343		/**
344		* Set the timeout in milliseconds of a currently open connection.
345		* Only call this method after a connection has been opened
346		* by {@link #connect connect()}.
347		* <p>
348		* @param timeout The timeout in milliseconds to use for the currently
349		* open socket connection.
350		* @exception SocketException If the operation fails.
351		*/
352		public void setSoTimeout(int timeout) throws SocketException
353		{
354	0	_socket_.setSoTimeout(timeout);
355	0	}
356
357
358		/**
359		* Returns the timeout in milliseconds of the currently opened socket.
360		* <p>
361		* @return The timeout in milliseconds of the currently opened socket.
362		* @exception SocketException If the operation fails.
363		*/
364		public int getSoTimeout() throws SocketException
365		{
366	0	return _socket_.getSoTimeout();
367		}
368
369		/**
370		* Enables or disables the Nagle's algorithm (TCP_NODELAY) on the
371		* currently opened socket.
372		* <p>
373		* @param on True if Nagle's algorithm is to be enabled, false if not.
374		* @exception SocketException If the operation fails.
375		*/
376		public void setTcpNoDelay(boolean on) throws SocketException
377		{
378	0	_socket_.setTcpNoDelay(on);
379	0	}
380
381
382		/**
383		* Returns true if Nagle's algorithm is enabled on the currently opened
384		* socket.
385		* <p>
386		* @return True if Nagle's algorithm is enabled on the currently opened
387		* socket, false otherwise.
388		* @exception SocketException If the operation fails.
389		*/
390		public boolean getTcpNoDelay() throws SocketException
391		{
392	0	return _socket_.getTcpNoDelay();
393		}
394
395
396		/**
397		* Sets the SO_LINGER timeout on the currently opened socket.
398		* <p>
399		* @param on True if linger is to be enabled, false if not.
400		* @param val The linger timeout (in hundredths of a second?)
401		* @exception SocketException If the operation fails.
402		*/
403		public void setSoLinger(boolean on, int val) throws SocketException
404		{
405	0	_socket_.setSoLinger(on, val);
406	0	}
407
408
409		/**
410		* Returns the current SO_LINGER timeout of the currently opened socket.
411		* <p>
412		* @return The current SO_LINGER timeout. If SO_LINGER is disabled returns
413		* -1.
414		* @exception SocketException If the operation fails.
415		*/
416		public int getSoLinger() throws SocketException
417		{
418	0	return _socket_.getSoLinger();
419		}
420
421
422		/**
423		* Returns the port number of the open socket on the local host used
424		* for the connection.
425		* <p>
426		* @return The port number of the open socket on the local host used
427		* for the connection.
428		*/
429		public int getLocalPort()
430		{
431	0	return _socket_.getLocalPort();
432		}
433
434
435		/**
436		* Returns the local address to which the client's socket is bound.
437		* <p>
438		* @return The local address to which the client's socket is bound.
439		*/
440		public InetAddress getLocalAddress()
441		{
442	0	return _socket_.getLocalAddress();
443		}
444
445		/**
446		* Returns the port number of the remote host to which the client is
447		* connected.
448		* <p>
449		* @return The port number of the remote host to which the client is
450		* connected.
451		*/
452		public int getRemotePort()
453		{
454	0	return _socket_.getPort();
455		}
456
457
458		/**
459		* @return The remote address to which the client is connected.
460		*/
461		public InetAddress getRemoteAddress()
462		{
463	0	return _socket_.getInetAddress();
464		}
465
466
467		/**
468		* Verifies that the remote end of the given socket is connected to the
469		* the same host that the SocketClient is currently connected to. This
470		* is useful for doing a quick security check when a client needs to
471		* accept a connection from a server, such as an FTP data connection or
472		* a BSD R command standard error stream.
473		* <p>
474		* @return True if the remote hosts are the same, false if not.
475		*/
476		public boolean verifyRemote(Socket socket)
477		{
478		InetAddress host1, host2;
479
480	0	host1 = socket.getInetAddress();
481	0	host2 = getRemoteAddress();
482
483	0	return host1.equals(host2);
484		}
485
486
487		/**
488		* Sets the SocketFactory used by the SocketClient to open socket
489		* connections. If the factory value is null, then a default
490		* factory is used (only do this to reset the factory after having
491		* previously altered it).
492		* <p>
493		* @param factory The new SocketFactory the SocketClient should use.
494		*/
495		public void setSocketFactory(SocketFactory factory)
496		{
497	0	if (factory == null)
498	0	_socketFactory_ = __DEFAULT_SOCKET_FACTORY;
499		else
500	0	_socketFactory_ = factory;
501	0	}
502		}
503
504

This report is generated by jcoverage, Maven and Maven JCoverage Plugin.