Package org.apache.commons.net.tftp

# Class TFTP

java.lang.Object
org.apache.commons.net.DatagramSocketClient
org.apache.commons.net.tftp.TFTP

All Implemented Interfaces:
  `AutoCloseable`

Direct Known Subclasses:
  `TFTPClient`

public class TFTP extends DatagramSocketClient
The TFTP class exposes a set of methods to allow you to deal with the TFTP protocol directly, in case you want to write your own TFTP client or server. However, almost every user should only be concerend with the `open()`, and `close()`, methods. Additionally,the a `setDefaultTimeout()` method may be of importance for performance tuning.

Details regarding the TFTP protocol and the format of TFTP packets can be found in RFC 783. But the point of these classes is to keep you from having to worry about the internals.

See Also:
  - `DatagramSocketClient`
  - `TFTPPacket`
  - `TFTPPacketException`
  - `TFTPClient`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ASCII_MODE`
  The ASCII transfer mode.
  `static final int`
  `BINARY_MODE`
  The binary transfer mode.
  `static final int`
  `DEFAULT_PORT`
  The default TFTP port according to RFC 783 is 69.
  `static final int`
  `DEFAULT_TIMEOUT`
  Deprecated.
  Use `DEFAULT_TIMEOUT_DURATION`.
  `static final Duration`
  `DEFAULT_TIMEOUT_DURATION`
  The default duration to wait to receive a datagram before timing out.
  `static final int`
  `IMAGE_MODE`
  The image transfer mode.
  `static final int`
  `NETASCII_MODE`
  The netascii transfer mode.
  `static final int`
  `OCTET_MODE`
  The octet transfer mode.

  ### Fields inherited from class org.apache.commons.net.DatagramSocketClient

  `_isOpen_, _socket_, _socketFactory_, _timeout_`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TFTP()`
  Creates a TFTP instance with a default timeout of `DEFAULT_TIMEOUT_DURATION`, a null socket, and buffered operations disabled.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `beginBufferedOps()`
  Initializes the internal buffers.
  `final TFTPPacket`
  `bufferedReceive()`
  This is a special method to perform a more efficient packet receive.
  `final void`
  `bufferedSend(TFTPPacket packet)`
  This is a special method to perform a more efficient packet send.
  `final void`
  `discardPackets()`
  This method synchronizes a connection by discarding all packets that may be in the local socket buffer.
  `final void`
  `endBufferedOps()`
  Releases the resources used to perform buffered sends and receives.
  `static final String`
  `getModeName(int mode)`
  Returns the TFTP string representation of a TFTP transfer mode.
  `int`
  `getPacketSize()`
  Gets the buffer size of the buffered used by `bufferedSend(TFTPPacket)` and `bufferedReceive()`.
  `final TFTPPacket`
  `receive()`
  Receives a TFTPPacket.
  `final void`
  `resetBuffersToSize(int packetSize)`
  Sets the size of the buffers used to receive and send packets.
  `final void`
  `send(TFTPPacket packet)`
  Sends a TFTP packet to its destination.
  `protected void`
  `trace(String direction, TFTPPacket packet)`
  Trace facility; this implementation does nothing.

  ### Methods inherited from class org.apache.commons.net.DatagramSocketClient

  `checkOpen, close, getCharset, getCharsetName, getDefaultTimeout, getDefaultTimeoutDuration, getLocalAddress, getLocalPort, getSoTimeout, getSoTimeoutDuration, isOpen, open, open, open, setCharset, setDatagramSocketFactory, setDefaultTimeout, setDefaultTimeout, setSoTimeout, setSoTimeout`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### ASCII_MODE

    public static final int ASCII_MODE
    The ASCII transfer mode. Its value is 0 and equivalent to NETASCII_MODE
    See Also:
      - Constant Field Values

  - ### NETASCII_MODE

    public static final int NETASCII_MODE
    The netascii transfer mode. Its value is 0.
    See Also:
      - Constant Field Values

  - ### BINARY_MODE

    public static final int BINARY_MODE
    The binary transfer mode. Its value is 1 and equivalent to OCTET_MODE.
    See Also:
      - Constant Field Values

  - ### IMAGE_MODE

    public static final int IMAGE_MODE
    The image transfer mode. Its value is 1 and equivalent to OCTET_MODE.
    See Also:
      - Constant Field Values

  - ### OCTET_MODE

    public static final int OCTET_MODE
    The octet transfer mode. Its value is 1.
    See Also:
      - Constant Field Values

  - ### DEFAULT_TIMEOUT

    @Deprecated public static final int DEFAULT_TIMEOUT
    Deprecated.
    Use `DEFAULT_TIMEOUT_DURATION`.
    The default number of milliseconds to wait to receive a datagram before timing out. The default is 5,000 milliseconds (5 seconds).
    See Also:
      - Constant Field Values

  - ### DEFAULT_TIMEOUT_DURATION

    public static final Duration DEFAULT_TIMEOUT_DURATION
    The default duration to wait to receive a datagram before timing out. The default is 5 seconds.
    Since:
      3.10.0

  - ### DEFAULT_PORT

    public static final int DEFAULT_PORT
    The default TFTP port according to RFC 783 is 69.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### TFTP

    public TFTP()
    Creates a TFTP instance with a default timeout of `DEFAULT_TIMEOUT_DURATION`, a null socket, and buffered operations disabled.

- ## Method Details

  - ### getModeName

    public static final String getModeName(int mode)
    Returns the TFTP string representation of a TFTP transfer mode. Will throw an ArrayIndexOutOfBoundsException if an invalid transfer mode is specified.
    Parameters:
      `mode` - The TFTP transfer mode. One of the MODE constants.
    Returns:
      The TFTP string representation of the TFTP transfer mode.

  - ### beginBufferedOps

    public final void beginBufferedOps()
    Initializes the internal buffers. Buffers are used by `bufferedSend()` and `bufferedReceive()`. This method must be called before calling either one of those two methods. When you finish using buffered operations, you must call `endBufferedOps()`.

  - ### bufferedReceive

    public final TFTPPacket bufferedReceive() throws IOException, InterruptedIOException, SocketException, TFTPPacketException
    This is a special method to perform a more efficient packet receive. It should only be used after calling `beginBufferedOps()`. beginBufferedOps() initializes a set of buffers used internally that prevent the new allocation of a DatagramPacket and byte array for each send and receive. To use these buffers you must call the bufferedReceive() and bufferedSend() methods instead of send() and receive(). You must also be certain that you don't manipulate the resulting packet in such a way that it interferes with future buffered operations. For example, a TFTPDataPacket received with bufferedReceive() will have a reference to the internal byte buffer. You must finish using this data before calling bufferedReceive() again, or else the data will be overwritten by the call.
    Returns:
      The TFTPPacket received.
    Throws:
      `InterruptedIOException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
      `SocketException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
      `IOException` - If some other I/O error occurs.
      `TFTPPacketException` - If an invalid TFTP packet is received.

  - ### bufferedSend

    public final void bufferedSend(TFTPPacket packet) throws IOException
    This is a special method to perform a more efficient packet send. It should only be used after calling `beginBufferedOps()`. beginBufferedOps() initializes a set of buffers used internally that prevent the new allocation of a DatagramPacket and byte array for each send and receive. To use these buffers you must call the bufferedReceive() and bufferedSend() methods instead of send() and receive(). You must also be certain that you don't manipulate the resulting packet in such a way that it interferes with future buffered operations. For example, a TFTPDataPacket received with bufferedReceive() will have a reference to the internal byte buffer. You must finish using this data before calling bufferedReceive() again, or else the data will be overwritten by the call.
    Parameters:
      `packet` - The TFTP packet to send.
    Throws:
      `IOException` - If some I/O error occurs.

  - ### discardPackets

    public final void discardPackets() throws IOException
    This method synchronizes a connection by discarding all packets that may be in the local socket buffer. This method need only be called when you implement your own TFTP client or server.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### endBufferedOps

    public final void endBufferedOps()
    Releases the resources used to perform buffered sends and receives.

  - ### getPacketSize

    public int getPacketSize()
    Gets the buffer size of the buffered used by `bufferedSend(TFTPPacket)` and `bufferedReceive()`.
    Returns:
      current buffer size
    Since:
      3.12.0

  - ### receive

    public final TFTPPacket receive() throws IOException, InterruptedIOException, SocketException, TFTPPacketException
    Receives a TFTPPacket.
    Returns:
      The TFTPPacket received.
    Throws:
      `InterruptedIOException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
      `SocketException` - If a socket timeout occurs. The Java documentation claims an InterruptedIOException is thrown on a DatagramSocket timeout, but in practice we find a SocketException is thrown. You should catch both to be safe.
      `IOException` - If some other I/O error occurs.
      `TFTPPacketException` - If an invalid TFTP packet is received.

  - ### resetBuffersToSize

    public final void resetBuffersToSize(int packetSize)
    Sets the size of the buffers used to receive and send packets. This method can be used to increase the size of the buffer to support `blksize`. For which valid values range between "8" and "65464" octets (RFC-2348). This only refers to the number of data octets, it does not include the four octets of TFTP header.
    Parameters:
      `packetSize` - The size of the data octets not including 4 octets for the header.
    Since:
      3.12.0

  - ### send

    public final void send(TFTPPacket packet) throws IOException
    Sends a TFTP packet to its destination.
    Parameters:
      `packet` - The TFTP packet to send.
    Throws:
      `IOException` - If some I/O error occurs.

  - ### trace

    protected void trace(String direction, TFTPPacket packet)
    Trace facility; this implementation does nothing.

    Override it to trace the data, for example:
    `System.out.println(direction + " " + packet.toString());`

    Parameters:
      `direction` - `>` or `<`
      `packet` - the packet to be sent or that has been received respectively
    Since:
      3.6