org.apache.commons.net.tftp

## Class TFTPClient

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

- All Implemented Interfaces:
    AutoCloseable

      public class TFTPClient
      extends TFTP

  The TFTPClient class encapsulates all the aspects of the TFTP protocol necessary to receive and send files through TFTP. It is derived from the `TFTP` because it is more convenient than using aggregation, and as a result exposes the same set of methods to allow you to deal with the TFTP protocol directly. However, almost every user should only be concerend with the the `open()`, `close()`, `sendFile()`, and `receiveFile()` methods. Additionally, the `setMaxTimeouts()` and `setDefaultTimeout()` methods 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:
    `TFTP`, `TFTPPacket`, `TFTPPacketException`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_MAX_TIMEOUTS` The default number of times a `receive` attempt is allowed to timeout before ending attempts to retry the `receive` and failing.

    - ### Fields inherited from class org.apache.commons.net.tftp.TFTP

      `ASCII_MODE, BINARY_MODE, DEFAULT_PORT, DEFAULT_TIMEOUT_DURATION, IMAGE_MODE, NETASCII_MODE, OCTET_MODE, PACKET_SIZE, sendBuffer`

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

      `_isOpen_, _socket_, _socketFactory_, _timeout_`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TFTPClient()` Creates a TFTPClient instance with a default timeout of DEFAULT_TIMEOUT, maximum timeouts value of DEFAULT_MAX_TIMEOUTS, a null socket, and buffered operations disabled.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getMaxTimeouts()` Gets the maximum number of times a `receive` attempt is allowed to timeout before ending attempts to retry the `receive` and failing.
    `long` | `getTotalBytesReceived()` Gets the number of bytes received in the ongoing download.
    `long` | `getTotalBytesSent()` Gets the number of bytes sent in the ongoing download.
    `int` | `receiveFile(String fileName, int mode, OutputStream output, InetAddress host)` Same as calling receiveFile(fileName, mode, output, host, TFTP.DEFAULT_PORT).
    `int` | `receiveFile(String fileName, int mode, OutputStream output, InetAddress host, int port)` Requests a named file from a remote host, writes the file to an OutputStream, closes the connection, and returns the number of bytes read.
    `int` | `receiveFile(String fileName, int mode, OutputStream output, String hostname)` Same as calling receiveFile(fileName, mode, output, hostname, TFTP.DEFAULT_PORT).
    `int` | `receiveFile(String fileName, int mode, OutputStream output, String hostname, int port)` Requests a named file from a remote host, writes the file to an OutputStream, closes the connection, and returns the number of bytes read.
    `void` | `sendFile(String fileName, int mode, InputStream input, InetAddress host)` Same as calling sendFile(fileName, mode, input, host, TFTP.DEFAULT_PORT).
    `void` | `sendFile(String fileName, int mode, InputStream input, InetAddress host, int port)` Requests to send a file to a remote host, reads the file from an InputStream, sends the file to the remote host, and closes the connection.
    `void` | `sendFile(String fileName, int mode, InputStream input, String hostname)` Same as calling sendFile(fileName, mode, input, hostname, TFTP.DEFAULT_PORT).
    `void` | `sendFile(String fileName, int mode, InputStream input, String hostname, int port)` Requests to send a file to a remote host, reads the file from an InputStream, sends the file to the remote host, and closes the connection.
    `void` | `setMaxTimeouts(int numTimeouts)` Sets the maximum number of times a `receive` attempt is allowed to timeout during a receiveFile() or sendFile() operation before ending attempts to retry the `receive` and failing.

    - ### Methods inherited from class org.apache.commons.net.tftp.TFTP

      `beginBufferedOps, bufferedReceive, bufferedSend, discardPackets, endBufferedOps, getModeName, getPacketSize, receive, resetBuffersToSize, send, trace`

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

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

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

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

- - ### Field Detail

    - #### DEFAULT_MAX_TIMEOUTS

          public static final int DEFAULT_MAX_TIMEOUTS

      The default number of times a `receive` attempt is allowed to timeout before ending attempts to retry the `receive` and failing. The default is 5 timeouts.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TFTPClient

          public TFTPClient()

      Creates a TFTPClient instance with a default timeout of DEFAULT_TIMEOUT, maximum timeouts value of DEFAULT_MAX_TIMEOUTS, a null socket, and buffered operations disabled.

  - ### Method Detail

    - #### getMaxTimeouts

          public int getMaxTimeouts()

      Gets the maximum number of times a `receive` attempt is allowed to timeout before ending attempts to retry the `receive` and failing.
      Returns:
        The maximum number of timeouts allowed.

    - #### getTotalBytesReceived

          public long getTotalBytesReceived()

      Gets the number of bytes received in the ongoing download.
      Returns:
        The number of bytes received in the ongoing download.

    - #### getTotalBytesSent

          public long getTotalBytesSent()

      Gets the number of bytes sent in the ongoing download.
      Returns:
        The number of bytes sent in the ongoing download.

    - #### receiveFile

          public int receiveFile(String fileName,
                                 int mode,
                                 OutputStream output,
                                 InetAddress host)
                          throws IOException

      Same as calling receiveFile(fileName, mode, output, host, TFTP.DEFAULT_PORT).
      Parameters:
        `fileName` - The name of the file to receive.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `output` - The OutputStream to which the file should be written.
        `host` - The remote host serving the file.
      Returns:
        number of bytes read
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.

    - #### receiveFile

          public int receiveFile(String fileName,
                                 int mode,
                                 OutputStream output,
                                 InetAddress host,
                                 int port)
                          throws IOException

      Requests a named file from a remote host, writes the file to an OutputStream, closes the connection, and returns the number of bytes read. A local UDP socket must first be created by `open()` before invoking this method. This method will not close the OutputStream containing the file; you must close it after the method invocation.
      Parameters:
        `fileName` - The name of the file to receive.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `output` - The OutputStream to which the file should be written.
        `host` - The remote host serving the file.
        `port` - The port number of the remote TFTP server.
      Returns:
        number of bytes read
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.

    - #### receiveFile

          public int receiveFile(String fileName,
                                 int mode,
                                 OutputStream output,
                                 String hostname)
                          throws UnknownHostException,
                                 IOException

      Same as calling receiveFile(fileName, mode, output, hostname, TFTP.DEFAULT_PORT).
      Parameters:
        `fileName` - The name of the file to receive.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `output` - The OutputStream to which the file should be written.
        `hostname` - The name of the remote host serving the file.
      Returns:
        number of bytes read
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.
        `UnknownHostException` - If the hostname cannot be resolved.

    - #### receiveFile

          public int receiveFile(String fileName,
                                 int mode,
                                 OutputStream output,
                                 String hostname,
                                 int port)
                          throws UnknownHostException,
                                 IOException

      Requests a named file from a remote host, writes the file to an OutputStream, closes the connection, and returns the number of bytes read. A local UDP socket must first be created by `open()` before invoking this method. This method will not close the OutputStream containing the file; you must close it after the method invocation.
      Parameters:
        `fileName` - The name of the file to receive.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `output` - The OutputStream to which the file should be written.
        `hostname` - The name of the remote host serving the file.
        `port` - The port number of the remote TFTP server.
      Returns:
        number of bytes read
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.
        `UnknownHostException` - If the hostname cannot be resolved.

    - #### sendFile

          public void sendFile(String fileName,
                               int mode,
                               InputStream input,
                               InetAddress host)
                        throws IOException

      Same as calling sendFile(fileName, mode, input, host, TFTP.DEFAULT_PORT).
      Parameters:
        `fileName` - The name the remote server should use when creating the file on its file system.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `input` - the input stream containing the data to be sent
        `host` - The name of the remote host receiving the file.
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.
        `UnknownHostException` - If the hostname cannot be resolved.

    - #### sendFile

          public void sendFile(String fileName,
                               int mode,
                               InputStream input,
                               InetAddress host,
                               int port)
                        throws IOException

      Requests to send a file to a remote host, reads the file from an InputStream, sends the file to the remote host, and closes the connection. A local UDP socket must first be created by `open()` before invoking this method. This method will not close the InputStream containing the file; you must close it after the method invocation.
      Parameters:
        `fileName` - The name the remote server should use when creating the file on its file system.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `input` - the input stream containing the data to be sent
        `host` - The remote host receiving the file.
        `port` - The port number of the remote TFTP server.
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.

    - #### sendFile

          public void sendFile(String fileName,
                               int mode,
                               InputStream input,
                               String hostname)
                        throws UnknownHostException,
                               IOException

      Same as calling sendFile(fileName, mode, input, hostname, TFTP.DEFAULT_PORT).
      Parameters:
        `fileName` - The name the remote server should use when creating the file on its file system.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `input` - the input stream containing the data to be sent
        `hostname` - The name of the remote host receiving the file.
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.
        `UnknownHostException` - If the hostname cannot be resolved.

    - #### sendFile

          public void sendFile(String fileName,
                               int mode,
                               InputStream input,
                               String hostname,
                               int port)
                        throws UnknownHostException,
                               IOException

      Requests to send a file to a remote host, reads the file from an InputStream, sends the file to the remote host, and closes the connection. A local UDP socket must first be created by `open()` before invoking this method. This method will not close the InputStream containing the file; you must close it after the method invocation.
      Parameters:
        `fileName` - The name the remote server should use when creating the file on its file system.
        `mode` - The TFTP mode of the transfer (one of the MODE constants).
        `input` - the input stream containing the data to be sent
        `hostname` - The name of the remote host receiving the file.
        `port` - The port number of the remote TFTP server.
      Throws:
        `IOException` - If an I/O error occurs. The nature of the error will be reported in the message.
        `UnknownHostException` - If the hostname cannot be resolved.

    - #### setMaxTimeouts

          public void setMaxTimeouts(int numTimeouts)

      Sets the maximum number of times a `receive` attempt is allowed to timeout during a receiveFile() or sendFile() operation before ending attempts to retry the `receive` and failing. The default is DEFAULT_MAX_TIMEOUTS.
      Parameters:
        `numTimeouts` - The maximum number of timeouts to allow. Values less than 1 should not be used, but if they are, they are treated as 1.