View Javadoc
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