    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