    View Javadoc
    1   package org.apache.commons.net.tftp;
    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.io.IOException;
    58  import java.io.InterruptedIOException;
    59  import java.net.DatagramPacket;
    60  import java.net.SocketException;
    61  import org.apache.commons.net.DatagramSocketClient;
    62
    63  /****
    64   * The TFTP class exposes a set of methods to allow you to deal with the TFTP
    65   * protocol directly, in case you want to write your own TFTP client or
    66   * server.  However, almost every user should only be concerend with
    67   * the <a href="org.apache.commons.net.DatagramSocketClient.html#open"> open() </a>,
    68   * and <a href="org.apache.commons.net.DatagramSocketClient.html#close"> close() </a>,
    69   * methods. Additionally,the a
    70   * <a href="org.apache.commons.net.DatagramSocketClient.html#setDefaultTimeout">
    71   * setDefaultTimeout() </a> method may be of importance for performance tuning.
    72   * <p>
    73   * Details regarding the TFTP protocol and the format of TFTP packets can
    74   * be found in RFC 783.  But the point of these classes is to keep you
    75   * from having to worry about the internals.
    76   * <p>
    77   * <p>
    78   * @author Daniel F. Savarese
    79   * @see org.apache.commons.net.DatagramSocketClient
    80   * @see TFTPPacket
    81   * @see TFTPPacketException
    82   * @see TFTPClient
    83   ***/
    84
    85  public class TFTP extends DatagramSocketClient
    86  {
    87      /****
    88       * The ascii transfer mode.  Its value is 0 and equivalent to NETASCII_MODE
    89       ***/
    90      public static final int ASCII_MODE = 0;
    91
    92      /****
    93       * The netascii transfer mode.  Its value is 0.
    94       ***/
    95      public static final int NETASCII_MODE = 0;
    96
    97      /****
    98       * The binary transfer mode.  Its value is 1 and equivalent to OCTET_MODE.
    99       ***/
    100     public static final int BINARY_MODE = 1;
    101
    102     /****
    103      * The image transfer mode.  Its value is 1 and equivalent to OCTET_MODE.
    104      ***/
    105     public static final int IMAGE_MODE = 1;
    106
    107     /****
    108      * The octet transfer mode.  Its value is 1.
    109      ***/
    110     public static final int OCTET_MODE = 1;
    111
    112     /****
    113      * The default number of milliseconds to wait to receive a datagram
    114      * before timing out.  The default is 5000 milliseconds (5 seconds).
    115      ***/
    116     public static final int DEFAULT_TIMEOUT = 5000;
    117
    118     /****
    119      * The default TFTP port according to RFC 783 is 69.
    120      ***/
    121     public static final int DEFAULT_PORT = 69;
    122
    123     /****
    124      * The size to use for TFTP packet buffers.  Its 4 plus the
    125      * TFTPPacket.SEGMENT_SIZE, i.e. 516.
    126      ***/
    127     static final int PACKET_SIZE = TFTPPacket.SEGMENT_SIZE + 4;
    128
    129     /**** A buffer used to accelerate receives in bufferedReceive() ***/
    130     private byte[] __receiveBuffer;
    131
    132     /**** A datagram used to minimize memory allocation in bufferedReceive() ***/
    133     private DatagramPacket __receiveDatagram;
    134
    135     /**** A datagram used to minimize memory allocation in bufferedSend() ***/
    136     private DatagramPacket __sendDatagram;
    137
    138     /****
    139      * A buffer used to accelerate sends in bufferedSend().
    140      * It is left package visible so that TFTPClient may be slightly more
    141      * efficient during file sends.  It saves the creation of an
    142      * additional buffer and prevents a buffer copy in _newDataPcket().
    143      ***/
    144     byte[] _sendBuffer;
    145
    146
    147     /****
    148      * Returns the TFTP string representation of a TFTP transfer mode.
    149      * Will throw an ArrayIndexOutOfBoundsException if an invalid transfer
    150      * mode is specified.
    151      * <p>
    152      * @param mode  The TFTP transfer mode.  One of the MODE constants.
    153      * @return  The TFTP string representation of the TFTP transfer mode.
    154      ***/
    155     public static final String getModeName(int mode)
    156     {
    157         return TFTPRequestPacket._modeStrings[mode];
    158     }
    159
    160     /****
    161      * Creates a TFTP instance with a default timeout of DEFAULT_TIMEOUT,
    162      * a null socket, and buffered operations disabled.
    163      ***/
    164     public TFTP()
    165     {
    166         setDefaultTimeout(DEFAULT_TIMEOUT);
    167         __receiveBuffer = null;
    168         __receiveDatagram = null;
    169     }
    170
    171     /****
    172      * This method synchronizes a connection by discarding all packets that
    173      * may be in the local socket buffer.  This method need only be called
    174      * when you implement your own TFTP client or server.
    175      * <p>
    176      * @exception IOException if an I/O error occurs.
    177      ***/
    178     public final void discardPackets() throws IOException
    179     {
    180         int to;
    181         DatagramPacket datagram;
    182
    183         datagram = new DatagramPacket(new byte[PACKET_SIZE], PACKET_SIZE);
    184
    185         to = getSoTimeout();
    186         setSoTimeout(1);
    187
    188         try
    189         {
    190             while (true)
    191                 _socket_.receive(datagram);
    192         }
    193         catch (SocketException e)
    194         {
    195             // Do nothing.  We timed out so we hope we're caught up.
    196         }
    197         catch (InterruptedIOException e)
    198         {
    199             // Do nothing.  We timed out so we hope we're caught up.
    200         }
    201
    202         setSoTimeout(to);
    203     }
    204
    205
    206     /****
    207      * This is a special method to perform a more efficient packet receive.
    208      * It should only be used after calling
    209      * <a href="#beginBufferedOps"> beginBufferedOps() </a>.  beginBufferedOps()
    210      * initializes a set of buffers used internally that prevent the new
    211      * allocation of a DatagramPacket and byte array for each send and receive.
    212      * To use these buffers you must call the bufferedReceive() and
    213      * bufferedSend() methods instead of send() and receive().  You must
    214      * also be certain that you don't manipulate the resulting packet in
    215      * such a way that it interferes with future buffered operations.
    216      * For example, a TFTPDataPacket received with bufferedReceive() will
    217      * have a reference to the internal byte buffer.  You must finish using
    218      * this data before calling bufferedReceive() again, or else the data
    219      * will be overwritten by the the call.
    220      * <p>
    221      * @return The TFTPPacket received.
    222      * @exception InterruptedIOException  If a socket timeout occurs.  The
    223      *       Java documentation claims an InterruptedIOException is thrown
    224      *       on a DatagramSocket timeout, but in practice we find a
    225      *       SocketException is thrown.  You should catch both to be safe.
    226      * @exception SocketException  If a socket timeout occurs.  The
    227      *       Java documentation claims an InterruptedIOException is thrown
    228      *       on a DatagramSocket timeout, but in practice we find a
    229      *       SocketException is thrown.  You should catch both to be safe.
    230      * @exception IOException  If some other I/O error occurs.
    231      * @exception TFTPPacketException If an invalid TFTP packet is received.
    232      ***/
    233     public final TFTPPacket bufferedReceive() throws IOException,
    234                 InterruptedIOException, SocketException, TFTPPacketException
    235     {
    236         __receiveDatagram.setData(__receiveBuffer);
    237         __receiveDatagram.setLength(__receiveBuffer.length);
    238         _socket_.receive(__receiveDatagram);
    239
    240         return TFTPPacket.newTFTPPacket(__receiveDatagram);
    241     }
    242
    243     /****
    244      * This is a special method to perform a more efficient packet send.
    245      * It should only be used after calling
    246      * <a href="#beginBufferedOps"> beginBufferedOps() </a>.  beginBufferedOps()
    247      * initializes a set of buffers used internally that prevent the new
    248      * allocation of a DatagramPacket and byte array for each send and receive.
    249      * To use these buffers you must call the bufferedReceive() and
    250      * bufferedSend() methods instead of send() and receive().  You must
    251      * also be certain that you don't manipulate the resulting packet in
    252      * such a way that it interferes with future buffered operations.
    253      * For example, a TFTPDataPacket received with bufferedReceive() will
    254      * have a reference to the internal byte buffer.  You must finish using
    255      * this data before calling bufferedReceive() again, or else the data
    256      * will be overwritten by the the call.
    257      * <p>
    258      * @param TFTPPacket  The TFTP packet to send.
    259      * @exception IOException  If some  I/O error occurs.
    260      ***/
    261     public final void bufferedSend(TFTPPacket packet) throws IOException
    262     {
    263         _socket_.send(packet._newDatagram(__sendDatagram, _sendBuffer));
    264     }
    265
    266
    267     /****
    268      * Initializes the internal buffers. Buffers are used by
    269      * <a href="#bufferedSend"> bufferedSend() </a> and
    270      * <a href="#bufferedReceive"> bufferedReceive() </a>.  This
    271      * method must be called before calling either one of those two
    272      * methods.  When you finish using buffered operations, you must
    273      * call <a href="#endBufferedOps"> endBufferedOps() </a>.
    274      ***/
    275     public final void beginBufferedOps()
    276     {
    277         __receiveBuffer = new byte[PACKET_SIZE];
    278         __receiveDatagram =
    279             new DatagramPacket(__receiveBuffer, __receiveBuffer.length);
    280         _sendBuffer = new byte[PACKET_SIZE];
    281         __sendDatagram =
    282             new DatagramPacket(_sendBuffer, _sendBuffer.length);
    283     }
    284
    285     /****
    286      * Releases the resources used to perform buffered sends and receives.
    287      ***/
    288     public final void endBufferedOps()
    289     {
    290         __receiveBuffer = null;
    291         __receiveDatagram = null;
    292         _sendBuffer = null;
    293         __sendDatagram = null;
    294     }
    295
    296
    297     /****
    298      * Sends a TFTP packet to its destination.
    299      * <p>
    300      * @param TFTPPacket  The TFTP packet to send.
    301      * @exception IOException  If some  I/O error occurs.
    302      ***/
    303     public final void send(TFTPPacket packet) throws IOException
    304     {
    305         _socket_.send(packet.newDatagram());
    306     }
    307
    308
    309     /****
    310      * Receives a TFTPPacket.
    311      * <p>
    312      * @return The TFTPPacket received.
    313      * @exception InterruptedIOException  If a socket timeout occurs.  The
    314      *       Java documentation claims an InterruptedIOException is thrown
    315      *       on a DatagramSocket timeout, but in practice we find a
    316      *       SocketException is thrown.  You should catch both to be safe.
    317      * @exception SocketException  If a socket timeout occurs.  The
    318      *       Java documentation claims an InterruptedIOException is thrown
    319      *       on a DatagramSocket timeout, but in practice we find a
    320      *       SocketException is thrown.  You should catch both to be safe.
    321      * @exception IOException  If some other I/O error occurs.
    322      * @exception TFTPPacketException If an invalid TFTP packet is received.
    323      ***/
    324     public final TFTPPacket receive() throws IOException, InterruptedIOException,
    325                 SocketException, TFTPPacketException
    326     {
    327         DatagramPacket packet;
    328
    329         packet = new DatagramPacket(new byte[PACKET_SIZE], PACKET_SIZE);
    330
    331         _socket_.receive(packet);
    332
    333         return TFTPPacket.newTFTPPacket(packet);
    334     }
    335
    336
    337 }

This page was automatically generated by Maven