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 and Description
static int	ASCII_MODE The ASCII transfer mode.
static int	BINARY_MODE The binary transfer mode.
static int	DEFAULT_PORT The default TFTP port according to RFC 783 is 69.
static java.time.Duration	DEFAULT_TIMEOUT_DURATION The default duration to wait to receive a datagram before timing out.
static int	IMAGE_MODE The image transfer mode.
static int	NETASCII_MODE The netascii transfer mode.
static int	OCTET_MODE The octet transfer mode.
(package private) static int	PACKET_SIZE The size to use for TFTP packet buffers.
(package private) byte[]	sendBuffer A buffer used to accelerate sends in bufferedSend().

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

_isOpen_, _socket_, _socketFactory_, _timeout_

Constructor Summary

Constructors

Constructor and 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 and Description
void	beginBufferedOps() Initializes the internal buffers.
TFTPPacket	bufferedReceive() This is a special method to perform a more efficient packet receive.
void	bufferedSend(TFTPPacket packet) This is a special method to perform a more efficient packet send.
void	discardPackets() This method synchronizes a connection by discarding all packets that may be in the local socket buffer.
void	endBufferedOps() Releases the resources used to perform buffered sends and receives.
static 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().
TFTPPacket	receive() Receives a TFTPPacket.
void	resetBuffersToSize(int packetSize) Sets the size of the buffers used to receive and send packets.
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, 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

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

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

DEFAULT_PORT

public static final int DEFAULT_PORT

The default TFTP port according to RFC 783 is 69.

See Also:

Constant Field Values

DEFAULT_TIMEOUT_DURATION

public static final java.time.Duration DEFAULT_TIMEOUT_DURATION

The default duration to wait to receive a datagram before timing out. The default is 5 seconds.

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

NETASCII_MODE

public static final int NETASCII_MODE

The netascii transfer mode. Its value is 0.

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

PACKET_SIZE

static final int PACKET_SIZE

The size to use for TFTP packet buffers. Its 4 plus the TFTPPacket.SEGMENT_SIZE, i.e. 516.

See Also:

Constant Field Values

sendBuffer

byte[] sendBuffer

A buffer used to accelerate sends in bufferedSend(). It is left package visible so that TFTPClient may be slightly more efficient during file sends. It saves the creation of an additional buffer and prevents a buffer copy in _newDataPcket().

Constructor Detail

TFTP

public TFTP()

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

Method Detail

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.

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.

getPacketSize

public int getPacketSize()

Gets the buffer size of the buffered used by bufferedSend(TFTPPacket) and bufferedReceive().

Returns:

current buffer size

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.

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