1 package org.apache.commons.net;
2
3 /* ====================================================================
4 * The Apache Software License, Version 1.1
5 *
6 * Copyright (c) 2001 The Apache Software Foundation. All rights
7 * reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * 1. Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in
18 * the documentation and/or other materials provided with the
19 * distribution.
20 *
21 * 3. The end-user documentation included with the redistribution,
22 * if any, must include the following acknowledgment:
23 * "This product includes software developed by the
24 * Apache Software Foundation (http://www.apache.org/)."
25 * Alternately, this acknowledgment may appear in the software itself,
26 * if and wherever such third-party acknowledgments normally appear.
27 *
28 * 4. The names "Apache" and "Apache Software Foundation" and
29 * "Apache Commons" must not be used to endorse or promote products
30 * derived from this software without prior written permission. For
31 * written permission, please contact apache@apache.org.
32 *
33 * 5. Products derived from this software may not be called "Apache",
34 * nor may "Apache" appear in their name, without
35 * prior written permission of the Apache Software Foundation.
36 *
37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48 * SUCH DAMAGE.
49 * ====================================================================
50 *
51 * This software consists of voluntary contributions made by many
52 * individuals on behalf of the Apache Software Foundation. For more
53 * information on the Apache Software Foundation, please see
54 * <http://www.apache.org/>.
55 */
56
57 import java.net.DatagramSocket;
58 import java.net.InetAddress;
59 import java.net.SocketException;
60
61 /****
62 * The DatagramSocketClient provides the basic operations that are required
63 * of client objects accessing datagram sockets. It is meant to be
64 * subclassed to avoid having to rewrite the same code over and over again
65 * to open a socket, close a socket, set timeouts, etc. Of special note
66 * is the <a href="#setDatagramSocketFactory"> setDatagramSocketFactory </a>
67 * method, which allows you to control the type of DatagramSocket the
68 * DatagramSocketClient creates for network communications. This is
69 * especially useful for adding things like proxy support as well as better
70 * support for applets. For
71 * example, you could create a
72 * <a href="org.apache.commons.net.DatagramSocketFactory.html">
73 * DatagramSocketFactory </a> that
74 * requests browser security capabilities before creating a socket.
75 * All classes derived from DatagramSocketClient should use the
76 * <a href="#_socketFactory_"> _socketFactory_ </a> member variable to
77 * create DatagramSocket instances rather than instantiating
78 * them by directly invoking a constructor. By honoring this contract
79 * you guarantee that a user will always be able to provide his own
80 * Socket implementations by substituting his own SocketFactory.
81 * <p>
82 * <p>
83 * @author Daniel F. Savarese
84 * @see DatagramSocketFactory
85 ***/
86
87 public abstract class DatagramSocketClient
88 {
89 /****
90 * The default DatagramSocketFactory shared by all DatagramSocketClient
91 * instances.
92 ***/
93 private static final DatagramSocketFactory __DEFAULT_SOCKET_FACTORY =
94 new DefaultDatagramSocketFactory();
95
96 /**** The timeout to use after opening a socket. ***/
97 protected int _timeout_;
98
99 /**** The datagram socket used for the connection. ***/
100 protected DatagramSocket _socket_;
101
102 /****
103 * A status variable indicating if the client's socket is currently open.
104 ***/
105 protected boolean _isOpen_;
106
107 /**** The datagram socket's DatagramSocketFactory. ***/
108 protected DatagramSocketFactory _socketFactory_;
109
110 /****
111 * Default constructor for DatagramSocketClient. Initializes
112 * _socket_ to null, _timeout_ to 0, and _isOpen_ to false.
113 ***/
114 public DatagramSocketClient()
115 {
116 _socket_ = null;
117 _timeout_ = 0;
118 _isOpen_ = false;
119 _socketFactory_ = __DEFAULT_SOCKET_FACTORY;
120 }
121
122
123 /****
124 * Opens a DatagramSocket on the local host at the first available port.
125 * Also sets the timeout on the socket to the default timeout set
126 * by <a href="#setDefaultTimeout"> setDefaultTimeout() </a>.
127 * <p>
128 * _isOpen_ is set to true after calling this method and _socket_
129 * is set to the newly opened socket.
130 * <p>
131 * @exception SocketException If the socket could not be opened or the
132 * timeout could not be set.
133 ***/
134 public void open() throws SocketException
135 {
136 _socket_ = _socketFactory_.createDatagramSocket();
137 _socket_.setSoTimeout(_timeout_);
138 _isOpen_ = true;
139 }
140
141
142 /****
143 * Opens a DatagramSocket on the local host at a specified port.
144 * Also sets the timeout on the socket to the default timeout set
145 * by <a href="#setDefaultTimeout"> setDefaultTimeout() </a>.
146 * <p>
147 * _isOpen_ is set to true after calling this method and _socket_
148 * is set to the newly opened socket.
149 * <p>
150 * @param port The port to use for the socket.
151 * @exception SocketException If the socket could not be opened or the
152 * timeout could not be set.
153 ***/
154 public void open(int port) throws SocketException
155 {
156 _socket_ = _socketFactory_.createDatagramSocket(port);
157 _socket_.setSoTimeout(_timeout_);
158 _isOpen_ = true;
159 }
160
161
162 /****
163 * Opens a DatagramSocket at the specified address on the local host
164 * at a specified port.
165 * Also sets the timeout on the socket to the default timeout set
166 * by <a href="#setDefaultTimeout"> setDefaultTimeout() </a>.
167 * <p>
168 * _isOpen_ is set to true after calling this method and _socket_
169 * is set to the newly opened socket.
170 * <p>
171 * @param port The port to use for the socket.
172 * @param laddr The local address to use.
173 * @exception SocketException If the socket could not be opened or the
174 * timeout could not be set.
175 ***/
176 public void open(int port, InetAddress laddr) throws SocketException
177 {
178 _socket_ = _socketFactory_.createDatagramSocket(port, laddr);
179 _socket_.setSoTimeout(_timeout_);
180 _isOpen_ = true;
181 }
182
183
184
185 /****
186 * Closes the DatagramSocket used for the connection.
187 * You should call this method after you've finished using the class
188 * instance and also before you call <a href="#open">open() </a>
189 * again. _isOpen_ is set to false and _socket_ is set to null.
190 * If you call this method when the client socket is not open,
191 * a NullPointerException is thrown.
192 ***/
193 public void close()
194 {
195 _socket_.close();
196 _socket_ = null;
197 _isOpen_ = false;
198 }
199
200
201 /****
202 * Returns true if the client has a currently open socket.
203 * <p>
204 * @return True if the client has a curerntly open socket, false otherwise.
205 ***/
206 public boolean isOpen()
207 {
208 return _isOpen_;
209 }
210
211
212 /****
213 * Set the default timeout in milliseconds to use when opening a socket.
214 * After a call to open, the timeout for the socket is set using this value.
215 * This method should be used prior to a call to <a href="#open">open()</a>
216 * and should not be confused with <a href="#setSoTimeout">setSoTimeout()</a>
217 * which operates on the currently open socket. _timeout_ contains
218 * the new timeout value.
219 * <p>
220 * @param timeout The timeout in milliseconds to use for the datagram socket
221 * connection.
222 ***/
223 public void setDefaultTimeout(int timeout)
224 {
225 _timeout_ = timeout;
226 }
227
228
229 /****
230 * Returns the default timeout in milliseconds that is used when
231 * opening a socket.
232 * <p>
233 * @return The default timeout in milliseconds that is used when
234 * opening a socket.
235 ***/
236 public int getDefaultTimeout()
237 {
238 return _timeout_;
239 }
240
241
242 /****
243 * Set the timeout in milliseconds of a currently open connection.
244 * Only call this method after a connection has been opened
245 * by <a href="#open">open()</a>.
246 * <p>
247 * @param timeout The timeout in milliseconds to use for the currently
248 * open datagram socket connection.
249 ***/
250 public void setSoTimeout(int timeout) throws SocketException
251 {
252 _socket_.setSoTimeout(timeout);
253 }
254
255
256 /****
257 * Returns the timeout in milliseconds of the currently opened socket.
258 * If you call this method when the client socket is not open,
259 * a NullPointerException is thrown.
260 * <p>
261 * @return The timeout in milliseconds of the currently opened socket.
262 ***/
263 public int getSoTimeout() throws SocketException
264 {
265 return _socket_.getSoTimeout();
266 }
267
268
269 /****
270 * Returns the port number of the open socket on the local host used
271 * for the connection. If you call this method when the client socket
272 * is not open, a NullPointerException is thrown.
273 * <p>
274 * @return The port number of the open socket on the local host used
275 * for the connection.
276 ***/
277 public int getLocalPort()
278 {
279 return _socket_.getLocalPort();
280 }
281
282
283 /****
284 * Returns the local address to which the client's socket is bound.
285 * If you call this method when the client socket is not open, a
286 * NullPointerException is thrown.
287 * <p>
288 * @return The local address to which the client's socket is bound.
289 ***/
290 public InetAddress getLocalAddress()
291 {
292 return _socket_.getLocalAddress();
293 }
294
295
296 /****
297 * Sets the DatagramSocketFactory used by the DatagramSocketClient
298 * to open DatagramSockets. If the factory value is null, then a default
299 * factory is used (only do this to reset the factory after having
300 * previously altered it).
301 * <p>
302 * @param factory The new DatagramSocketFactory the DatagramSocketClient
303 * should use.
304 ***/
305 public void setDatagramSocketFactory(DatagramSocketFactory factory)
306 {
307 if (factory == null)
308 _socketFactory_ = __DEFAULT_SOCKET_FACTORY;
309 else
310 _socketFactory_ = factory;
311 }
312 }
This page was automatically generated by Maven