Coverage report

  %line %branch
org.apache.commons.net.tftp.TFTP
0% 
0% 

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

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