LCM Software
TFTP Package v1.5

com.lcmsoft.tftp
Class TftpRequest

java.lang.Object
  extended by com.lcmsoft.tftp.TftpRequest

public class TftpRequest
extends java.lang.Object

Represents a TFTP request. It is the fundamental building block to implement both TFTP servers and TFTP clients. That is because TftpRequest can represent both requests to be sent to servers (used to implement TFTP clients) and requests received from clients (used to implement TFTP servers).

The class TftpRequest handles all low level details of the TFTP protocol, but the application logic must be implemented at a higher level. Although that requires some coding, it provides maximum flexibility. For that same reason, some knowledge of the TFTP standard is recommended in order to understand and explore all possibilites of the class, specially regarding TFTP options.

TFTP Strings

All strings passed as parameters to TftpRequest must be restricted to the characters available in the US-ASCII character set (the first 128 characters of the Unicode character set). That is a limitation of the TFTP protocol and using characters outside that range leads do undefined behaviour.

Whenever the TFTP standard defines strings as case insensitive (namely the transfer mode and options keys) TftpRequest always converts them to lowercase. That means that the case of case insensitive strings does not matter, whether the string is passed to the class by application logic or received from a remote host. Likewise, any case insensitive string the TftpRequest class returns or sends to a remote host is always lowercase only.

TFTP Option Extension

The class TftpRequest provides full support for TFTP options. Several methods are provided so that the application logic can set options, get their values or query the options of a TFTP request.

The class also understands the standard options in several ways, that is, it provides convenient constants for the standard options, provides a set of specific methods for them and, where applicable, the standard options affect the class behaviour if set (timeout and block size options). Other than that, all options are just exposed as received from the remote host and sent as set by the local host. That way it is possible to implement any custom options, if desired.

When a TftpRequest instance is constructed with the default constructor, it contains no options (that is intended to be used by TFTP clients). The application must use the provided methods to set the options desired. After connecting to the server (getInputStream() and getOutputStream()) the TftpRequest will contain only the options returned by the server (the options set by the application are lost). At this time, the query methods can be used to process any options returned by the server.

When a TftpRequest instance is constructed with the constructor that accepts a datagram, it will contain all options specified in the datagram (that is intended to be used by TFTP servers). The server must then use the provided methods to change and remove options as desired. When the request is answered (getInputStream() and getOutputStream()) all options set in the TftpRequest will be sent to the client as part of the answer.

Notice that a server (specially older ones) may not support the TFTP options extension and may understand TFTP options as an ill formed TFTP request, sending an error if options are used. In that case, the client will get an exception and it is up to the implementation to try the request again without any options.

Implementing a TFTP Client

Implementing a TFTP client using TftpRequest is straightforward. A basic TFTP client follows the following outline:

  1. construct a TftpRequest using the default constructor
  2. set the host address (setHost(java.net.InetAddress)) and port number (setPort(int)) of the server
  3. set the operation desired (setOperation(int)) and the file name (setFileName(java.lang.String))
  4. get an input stream (getInputStream()) for a read request, or an output stream (getOutputStream()) for a write one
  5. use the input stream/output stream to read data from/send data to the server
  6. close the stream
A full TFTP client, supporting all possibilites of the protocol, including TFTP options, is more complex though:
  1. construct a TftpRequest using the default constructor
  2. set the communication parameters (setDefaultTimeout(int), setRetries(int))
  3. set the host address (setHost(java.net.InetAddress)) and port number (setPort(int)) of the server
  4. set the operation desired (setOperation(int)) and the file name (setFileName(java.lang.String))
  5. set the transfer mode (setMode(java.lang.String)), if necessary
  6. set the standard options (setTimeout(int), setTransferSize(long), setBlockSize(int)), if desired
  7. set any additional custom option (setOption(String,String) and setOption(String,long)), if desired
  8. get an input stream (getInputStream()) for a read request, or an output stream (getOutputStream()) for a write one
  9. process the options returned by the server (optionsNames(), getOptionAsString(java.lang.String), getOptionAsLong(java.lang.String), getOptionAsInt(java.lang.String), isOptionSet(java.lang.String), isOptionValidAsLong(java.lang.String), isOptionValidAsInt(java.lang.String), getTimeout(), isTimeoutSet(), getTransferSize(), isTransferSizeSet(), getBlockSize(), isBlockSizeSet()), aborting if necessary (sendError(int, java.lang.String))
  10. use the input stream/output stream to read data from/send data to the server
  11. close the stream
Nothing prevents a TftpRequest object to be reused by repeating the steps 2 to 11 above, but care must be taken to reset all properties, as needed, for the next request.

Implementing a TFTP Server

Implementing a server requires more coding and more application logic, but it is not difficult either. A basic TFTP server could follow the following outline:
  1. get a TFTP request from a TFTP client (getRequest(int), getRequest())
  2. check the request parameters (getOperation() and getFileName()) and abort if the request can't be honored (sendError(int, java.lang.String))
  3. get an input stream (getInputStream()) for a write request, or an output stream (getOutputStream()) for a read one (notice that this is the inverse of the client)
  4. use the input stream/output stream to receive data from/send data to the client
  5. close the stream
  6. go back to the step 1
The following is an outline for a full featured server, supporting TFTP options:
  1. get a TFTP request from a TFTP client (getRequest(int), getRequest())
  2. check the request parameters (getOperation(), getFileName() and getMode()) and abort if the request can't be honored (sendError(int, java.lang.String))
  3. process the options sent by the client (optionsNames(), getOptionAsString(java.lang.String), getOptionAsLong(java.lang.String), getOptionAsInt(java.lang.String), isOptionSet(java.lang.String), isOptionValidAsLong(java.lang.String), isOptionValidAsInt(java.lang.String), getTimeout(), isTimeoutSet(), getTransferSize(), isTransferSizeSet(), getBlockSize()), isBlockSizeSet()), aborting if necessary (sendError(int, java.lang.String))
  4. set the options to be returned to the client (setTimeout(int), setTransferSize(long), setBlockSize(int), setOption(String,String), setOption(String,long), clearOptions(), clearOption(java.lang.String), clearTimeout(), clearTransferSize(), clearBlockSize()); notice that any option not explicitly set or cleared will keep the value sent by the client
  5. get an input stream (getInputStream()) for a write request, or an output stream (getOutputStream()) for a read one (notice that this is the inverse of the client)
  6. use the input stream/output stream to receive data from/send data to the client
  7. close the stream
  8. go back to the step 1
Notice that it is possible to implement a multithreaded server by creating a thread to process each request while the main thread waits for another one.


Field Summary
static java.lang.String BLOCK_SIZE
          String for the block size standard option.
static int DEFAULT_RETRIES
          Default number of retries.
static int DEFAULT_TIMEOUT
          Default timeout (seconds).
static java.lang.String MAIL
          String for the mail transfer mode.
static java.lang.String NETASCII
          String for the netascii transfer mode.
static java.lang.String OCTET
          String for the octet transfer mode.
static int READ
          Code for the read operation.
static int STANDARD_BLOCK_SIZE
          TFTP standard block size.
static int STANDARD_TFTP_PORT
          TFTP protocol standard port.
static java.lang.String TIMEOUT
          String for the timeout standard option.
static java.lang.String TRANSFER_SIZE
          String for the transfer size standard option.
static int WRITE
          Code for the write operation.
 
Constructor Summary
TftpRequest()
          Constructs a new TftpRequest.
 
Method Summary
static void abortGetRequest()
          Aborts an in-progress call to the methods getRequest(int) or getRequest().
 void clearBlockSize()
          Removes the block size standard option from this request.
 void clearOption(java.lang.String option)
          Removes an option from this request.
 void clearOptions()
          Removes all options from this request.
 void clearTimeout()
          Removes the timeout standard option from this request.
 void clearTransferSize()
          Removes the transfer size standard option from this request.
 int getBlockSize()
          Returns the value of the block size standard option.
 int getDefaultTimeout()
          Returns the default timeout.
 java.lang.String getFileName()
          Returns the file name of this request.
 java.net.InetAddress getHost()
          Returns the remote host address.
 java.io.InputStream getInputStream()
          Returns an InputStream object that receives data from the remote host.
 java.lang.String getMode()
          Returns the transfer mode of this request.
 int getOperation()
          Returns the operation this request performs.
 int getOptionAsInt(java.lang.String option)
          Returns the value of an option as an int value.
 long getOptionAsLong(java.lang.String option)
          Returns the value of an option as a long value.
 java.lang.String getOptionAsString(java.lang.String option)
          Returns the value of a string option.
 java.io.OutputStream getOutputStream()
          Returns an OutputStream object that receives data from the remote host.
 int getPort()
          Returns the remote host port.
static TftpRequest getRequest()
          Waits for an incoming client TFTP request on the standard TFTP port.
static TftpRequest getRequest(int port)
          Waits for an incoming client TFTP request on a given port.
 int getRequestBlockSize()
          Returns the block size being used by this request.
 int getRequestTimeout()
          Returns the timeout being used by this request.
 int getRetries()
          Returns the number of retries of this request.
 int getTimeout()
          Returns the value of the timeout standard option.
 long getTransferSize()
          Returns the value of the transfer size standard option.
 boolean isBlockSizeSet()
          Tests whether the block size standard option has been set.
 boolean isOptionSet(java.lang.String option)
          Tests whether an option is set or not.
 boolean isOptionValidAsInt(java.lang.String option)
          Tests whether an option has a valid int value.
 boolean isOptionValidAsLong(java.lang.String option)
          Tests whether an option has a valid long value.
 boolean isTimeoutSet()
          Tests whether the timeout standard option has been set.
 boolean isTransferSizeSet()
          Tests whether the transfer size standard option has been set.
 java.util.Iterator optionsNames()
          Returns an iterator over all options of this request.
 void sendError(int errorCode, java.lang.String errorMsg)
          Signals an error the the remote host.
 void setBlockSize(int blockSize)
          Sets the block size standard option.
 void setDefaultTimeout(int timeout)
          Sets the default timeout.
 void setFileName(java.lang.String fileName)
          Sets the file name for this request.
 void setHost(java.net.InetAddress host)
          Sets the address of the remote host.
 void setMode(java.lang.String mode)
          Sets the transfer mode for this request.
 void setOperation(int operation)
          Sets the operation this request should perform.
 void setOption(java.lang.String option, long value)
          Sets a numeric option for this request.
 void setOption(java.lang.String option, java.lang.String value)
          Sets a string option for this request.
 void setPort(int port)
          Sets the port of the remote host.
 void setRetries(int retries)
          Sets the number of retries for this request.
 void setTimeout(int timeout)
          Sets the timeout standard option.
 void setTransferSize(long transferSize)
          Sets the transfer size standard option.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_TIMEOUT

public static final int DEFAULT_TIMEOUT
Default timeout (seconds).

See Also:
Constant Field Values

DEFAULT_RETRIES

public static final int DEFAULT_RETRIES
Default number of retries.

See Also:
Constant Field Values

STANDARD_BLOCK_SIZE

public static final int STANDARD_BLOCK_SIZE
TFTP standard block size.

See Also:
Constant Field Values

STANDARD_TFTP_PORT

public static final int STANDARD_TFTP_PORT
TFTP protocol standard port.

See Also:
Constant Field Values

READ

public static final int READ
Code for the read operation.

See Also:
Constant Field Values

WRITE

public static final int WRITE
Code for the write operation.

See Also:
Constant Field Values

TIMEOUT

public static final java.lang.String TIMEOUT
String for the timeout standard option.

See Also:
Constant Field Values

TRANSFER_SIZE

public static final java.lang.String TRANSFER_SIZE
String for the transfer size standard option.

See Also:
Constant Field Values

BLOCK_SIZE

public static final java.lang.String BLOCK_SIZE
String for the block size standard option.

See Also:
Constant Field Values

NETASCII

public static final java.lang.String NETASCII
String for the netascii transfer mode.

See Also:
Constant Field Values

OCTET

public static final java.lang.String OCTET
String for the octet transfer mode.

See Also:
Constant Field Values

MAIL

public static final java.lang.String MAIL
String for the mail transfer mode.

See Also:
Constant Field Values
Constructor Detail

TftpRequest

public TftpRequest()
Constructs a new TftpRequest. Sets the default timeout to DEFAULT_TIMEOUT, the number of retries to DEFAULT_RETRIES, the port to STANDARD_TFTP_PORT and the transfer mode to OCTET. The constructor does not set any option.

Method Detail

getRequest

public static TftpRequest getRequest(int port)
                              throws java.io.IOException
Waits for an incoming client TFTP request on a given port. The request is returned as a TftpRequest object. The remote host address and port are set with the IP address and port of the sender, and the operation, file name, transfer mode and options with the values present in the TFTP request. The default timeout and number of retries are always set to DEFAULT_TIMEOUT and DEFAULT_RETRIES, respectively.

The request is assumed to have been sent by a TFTP client, however it is the application responsibility to make any validation (operation, file name, transfer mode, options and so on) necessary before proceeding.

Notice that the method listens for requests on all IP addresses of the local machine and blocks forever until a request is received. The method abortGetRequest() must be used to abort getRequest (in that case the application gets an exception).

Parameters:
port - port to listen (STANDARD_TFTP_PORT for the standard TFTP service port)
Returns:
a client TFTP request
Throws:
java.io.IOException - if an error occurs while waiting for a request
java.io.InterruptedIOException - if the method has been aborted by abortGetRequest()
See Also:
getRequest(), abortGetRequest()

getRequest

public static TftpRequest getRequest()
                              throws java.io.IOException
Waits for an incoming client TFTP request on the standard TFTP port. This method is the same as calling getRequest(int) passing STANDARD_TFTP_PORT as parameter.

Returns:
a client TFTP request
Throws:
java.io.IOException - if an error occurs while waiting for a request
java.io.InterruptedIOException - if the method has been aborted by abortGetRequest()
See Also:
getRequest(int), abortGetRequest()

abortGetRequest

public static void abortGetRequest()
                            throws java.io.IOException
Aborts an in-progress call to the methods getRequest(int) or getRequest(). If there is no call to the mentioned methods, abortGetRequest waits until one of them is called, so that when the method returns the call is guaranteed to be aborted and the thread, received an exception.

Notice that abortGetRequest must be called from another thread to produce the desired result, that is, interrupt the one that is blocked on getRequest(int) or getRequest(int).

Throws:
java.io.IOException - if a communication error occurs
See Also:
getRequest(int), getRequest()

setRetries

public void setRetries(int retries)
Sets the number of retries for this request. The number of retries is the number of times TftpRequest tries to send a packet again to the remote host if it does not answer. Notice that this is in addition to the first time, that is, if the number of retries is set to 3, TftpRequest will send a packet to the remote host 4 times before giving up, if it does not answer.

Parameters:
retries - number of retries
Throws:
java.lang.IllegalArgumentException - if the number of retries is less than zero

getRetries

public int getRetries()
Returns the number of retries of this request.

Returns:
the number of retries

setHost

public void setHost(java.net.InetAddress host)
Sets the address of the remote host.

Parameters:
host - the remote host address
Throws:
java.lang.IllegalArgumentException - if the host is null

getHost

public java.net.InetAddress getHost()
Returns the remote host address.

Returns:
the remote host address

setPort

public void setPort(int port)
Sets the port of the remote host.

Parameters:
port - the remote host port (STANDARD_TFTP_PORT for the standard port used by TFTP servers)
Throws:
java.lang.IllegalArgumentException - if port is outside the range from 1 to 65535

getPort

public int getPort()
Returns the remote host port.

Returns:
the remote host port

setOperation

public void setOperation(int operation)
Sets the operation this request should perform. The TFTP standard defines just two operations: reading a file from a server (READ) and writing a file to a server (WRITE).

Parameters:
operation - operation to perform

getOperation

public int getOperation()
Returns the operation this request performs.

Returns:
this request's operation

setFileName

public void setFileName(java.lang.String fileName)
Sets the file name for this request. The TFTP standard does not specify any convention for file names, so usually they depend on the server's system and implementation.

Parameters:
fileName - the file name
Throws:
java.lang.IllegalArgumentException - if the file name is null

getFileName

public java.lang.String getFileName()
Returns the file name of this request. The TftpRequest class does not interpret file names in any way, processing the file name is entirely up to the application logic.

Returns:
this request's file name

setMode

public void setMode(java.lang.String mode)
Sets the transfer mode for this request. The class TftpRequest provides convenient constants for the transfer modes defined by the TFTP protocol standard:

Notice that, whatever the transfer mode is, the class TftpRequest does not perform any conversion on the data, that must be done by the application logic, if necessary.

Parameters:
mode - transfer mode
Throws:
java.lang.IllegalArgumentException - if the transfer mode is null

getMode

public java.lang.String getMode()
Returns the transfer mode of this request.

Returns:
this request's transfer mode

optionsNames

public java.util.Iterator optionsNames()
Returns an iterator over all options of this request. The iterator iterates over the option names, that is, calling the iterator's next method returns the option name, as a String object. The iterator's remove method can be used to remove the last option returned, according the java.util.Iterator interface contract.

Returns:
an iterator over this request's options

setOption

public void setOption(java.lang.String option,
                      java.lang.String value)
Sets a string option for this request. If the option is already set, its value is replaced. The constants TIMEOUT, TRANSFER_SIZE and BLOCK_SIZE can be used to set the standard options.

Parameters:
option - option to set
value - value to set, passed as a String
Throws:
java.lang.IllegalArgumentException - if the option or the value is null

setOption

public void setOption(java.lang.String option,
                      long value)
Sets a numeric option for this request. This method is the same as setOption(String,String), but taking a long as the option value.

Parameters:
option - option to set
value - value to set, passed as a long

isOptionSet

public boolean isOptionSet(java.lang.String option)
Tests whether an option is set or not. This method tests whether a given option has been set (exists in this request). The constants TIMEOUT, TRANSFER_SIZE and BLOCK_SIZE can be used to test the standard options.

Parameters:
option - option to test
Returns:
true if the option is set, false otherwise

getOptionAsString

public java.lang.String getOptionAsString(java.lang.String option)
Returns the value of a string option. If the option is not set (does not exist in this request), returns null. The constants TIMEOUT, TRANSFER_SIZE and BLOCK_SIZE can be used to get the standard options.

Parameters:
option - option to return
Returns:
the value of the option, as a String, or null if not set

isOptionValidAsLong

public boolean isOptionValidAsLong(java.lang.String option)
Tests whether an option has a valid long value. The method isOptionValidAsLong tests whether the value of a given option (which is always a string) is a valid long value, that is, can be successfuly converted to a long.

The constant TRANSFER_SIZE can be used to test the transfer size standard option. Notice that the method throws an exception if the option does not exist. The method isOptionSet(java.lang.String) can be used to test this case.

Parameters:
option - option to test
Returns:
true if the option value can be converted to a long, false otherwise

getOptionAsLong

public long getOptionAsLong(java.lang.String option)
Returns the value of an option as a long value. This method is the same as getOptionAsString(java.lang.String), but returning the option value as a long. The constant TRANSFER_SIZE can be used to get the transfer size standard option.

Notice that the method throws an exception if the option does not exist or if its value is not a valid long. The methods isOptionSet(java.lang.String) and isOptionValidAsLong(java.lang.String) can be used to test for these cases.

Parameters:
option - option to return
Returns:
the value of the option, as a long

isOptionValidAsInt

public boolean isOptionValidAsInt(java.lang.String option)
Tests whether an option has a valid int value. The method isOptionValidAsInt tests whether the value of a given option (which is always a string) is a valid int value, that is, can be successfuly converted to an int.

The constants TIMEOUT and BLOCK_SIZE can be used to test the timeout and block size standard options. Notice that the method throws an exception if the option does not exist. The method isOptionSet(java.lang.String) can be used to test this case.

Parameters:
option - option to test
Returns:
true if the option value can be converted to an int, false otherwise

getOptionAsInt

public int getOptionAsInt(java.lang.String option)
Returns the value of an option as an int value. This method is the same as getOptionAsString(java.lang.String), but returning the option value as an int. The constants TIMEOUT and BLOCK_SIZE can be used to get the timeout and block size standard options.

Notice that the method throws an exception if the option does not exist or if its value is not a valid int. The methods isOptionSet(java.lang.String) and isOptionValidAsInt(java.lang.String) can be used to test for these cases.

Parameters:
option - option to return
Returns:
the value of the option, as an int

clearOption

public void clearOption(java.lang.String option)
Removes an option from this request. The constants TIMEOUT, TRANSFER_SIZE and BLOCK_SIZE can be used to remove the standard options.

Parameters:
option - option to remove

clearOptions

public void clearOptions()
Removes all options from this request.


setTimeout

public void setTimeout(int timeout)
Sets the timeout standard option. The method setTimeout is the same as calling the method setOption(String,long) with the constant TIMEOUT.

If the timeout standard option is set, the TftpRequest class uses the value specified as the timeout to talk to the remote host.

Parameters:
timeout - timeout to set, in seconds
See Also:
setDefaultTimeout(int), getRequestTimeout()

isTimeoutSet

public boolean isTimeoutSet()
Tests whether the timeout standard option has been set. This method is the same as calling the isOptionSet(java.lang.String) with the constant TIMEOUT.

Returns:
true if the timeout standard option is set in this request, false otherwise

getTimeout

public int getTimeout()
Returns the value of the timeout standard option. This method is the same as calling getOptionAsInt(java.lang.String) with the TIMEOUT constant.

Returns:
the value of the timeout standard option

clearTimeout

public void clearTimeout()
Removes the timeout standard option from this request. This method is the same as calling clearOption(java.lang.String) with the constant TIMEOUT.


setDefaultTimeout

public void setDefaultTimeout(int timeout)
Sets the default timeout. The default timeout is the timeout to use if the standard timeout option is not specified or is not valid.

Parameters:
timeout - default timeout, in seconds
Throws:
java.lang.IllegalArgumentException - if the timeout is less than or equal to zero
See Also:
setTimeout(int), getRequestTimeout()

getDefaultTimeout

public int getDefaultTimeout()
Returns the default timeout.

Returns:
the default timeout

getRequestTimeout

public int getRequestTimeout()
Returns the timeout being used by this request. This method returns the actual timeout being used by this TftpRequest. It is the value of the timeout standard option if it has been set and its value is valid (numeric and greater than zero) or the default timeout otherwise.

Returns:
this request's timeout
See Also:
setTimeout(int), setDefaultTimeout(int)

setTransferSize

public void setTransferSize(long transferSize)
Sets the transfer size standard option. The method setTransferSize is the same as calling the method setOption(String,long) with the constant TRANSFER_SIZE.

Parameters:
transferSize - value of the transfer size option

isTransferSizeSet

public boolean isTransferSizeSet()
Tests whether the transfer size standard option has been set. This method is the same as calling the isOptionSet(java.lang.String) with the constant TRANSFER_SIZE.

Returns:
true if the transfer size standard option is set in this request, false otherwise

getTransferSize

public long getTransferSize()
Returns the value of the transfer size standard option. This method is the same as calling getOptionAsLong(java.lang.String) with the TRANSFER_SIZE constant.

Returns:
the value of the transfer size standard option

clearTransferSize

public void clearTransferSize()
Removes the transfer size standard option from this request. This method is the same as calling clearOption(java.lang.String) with the constant TRANSFER_SIZE.


setBlockSize

public void setBlockSize(int blockSize)
Sets the block size standard option. The method setBlockSize is the same as calling the method setOption(String,long) with the constant BLOCK_SIZE.

If the block size standard option is set, the TftpRequest class uses the value specified as the block size for the request. If the block size option is not set, the standard block size, as determined by the TFTP specification, will be used.

Parameters:
blockSize - block size to set
See Also:
getRequestBlockSize()

isBlockSizeSet

public boolean isBlockSizeSet()
Tests whether the block size standard option has been set. This method is the same as calling the isOptionSet(java.lang.String) with the constant BLOCK_SIZE.

Returns:
true if the block size standard option is set in this request, false otherwise

getBlockSize

public int getBlockSize()
Returns the value of the block size standard option. This method is the same as calling getOptionAsInt(java.lang.String) with the BLOCK_SIZE constant.

Returns:
the value of the block size standard option

clearBlockSize

public void clearBlockSize()
Removes the block size standard option from this request. This method is the same as calling clearOption(java.lang.String) with the constant BLOCK_SIZE.


getRequestBlockSize

public int getRequestBlockSize()
Returns the block size being used by this request. This method returns the actual block size being used by this TftpRequest. It is the value of the block size standard option, if it has been set and if its value is valid (numeric and greater than zero) or STANDARD_BLOCK_SIZE otherwise.

Returns:
the request's block size
See Also:
setBlockSize(int)

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Returns an InputStream object that receives data from the remote host. The getInputStream operation depends on whether this TftpRequest operation property is READ or WRITE.

If it is READ, the method sends the request to the remote host (which is expected to be a TFTP server) according all properties and options, waits for its acknowledgement and returns an InputStream object that must be used to receive the file from the server. Also, after getInputStream returns, this TftpRequest will contain the options (if any) returned by the server.

If the operation is WRITE then it is supposed to be a request received from a TFTP client (returned by the methods getRequest(int) or getRequest()). In this case, getInputStream acknowledges the request to the client (sending any options set in this TftpRequest to it) and returns an InputStream object that must be used to receive the file from the client.

Any error that occurs either while establishing the connection or while reading the InputStream throws an IOException. The exact class depends on the nature of the error and version of the JVM, however if the error was signaled by the remote host then the exception will be an instance of the TftpErrorException class.

At any time the application can abort the request by calling the method sendError(int, java.lang.String), which signals an error to the remote host. If multithreading is being used, calling the close() method of the returned InputStream object makes any thread blocked on it to get an exception.

Notice that the close() method of the InputStream object returned must be called after all data have been written, otherwise the last data block will not be acknowledged, causing the remote host to timeout.

Returns:
an InputStream to receive data from the remote host; notice that encapsulating the stream on a BufferedInputStream does not improve the performance
Throws:
java.io.IOException - if a communication error or timeout occurs or if the remote host signals an error
java.lang.IllegalStateException - if the host or file name were not specified (they are null) or if the operation is not valid

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
Returns an OutputStream object that receives data from the remote host. The getOutputStream operation depends on whether this TftpRequest operation property is WRITE or READ.

If it is WRITE, the method sends the request to the remote host (which is expected to be a TFTP server) according all properties and options, waits for its acknowledgement and returns an OutputStream object that must be used to send the file to the server. Also, after getOutputStream returns, this TftpRequest will contain the options (if any) returned by the server.

If the operation is READ then it is supposed to be a request received from a TFTP client (returned by the methods getRequest(int) or getRequest()). In this case, getOutputStream acknowledge the request to the client (sending any options set in this TftpRequest to it) and returns an OutputStream object that must be used to send the file to the client.

Any error that occurs either while establishing the connection or while writing to the OutputStream throws an IOException. The exact class depends on the nature of the error and version of the JVM, however if the error was signaled by the remote host then the exception will be an instance of the TftpErrorException class.

At any time the application can abort the request by calling the method sendError(int, java.lang.String), which signals an error to the remote host. If multithreading is being used, calling the close() method of the returned OutputStream object makes any thread blocked on it to get an exception.

Notice that the close() method of the OutputStream object returned must be called after all data have been written, otherwise the last data block will not be sent to the remote host and the request will fail.

Returns:
an OutputStream to send data to the remote host; notice that encapsulating the stream on a BufferedOutputStream does not improve the performance
Throws:
java.io.IOException - if a communication error or timeout occurs or if the remote host signals an error
java.lang.IllegalStateException - if the host or file name were not specified (they are null) or if the operation is not valid

sendError

public void sendError(int errorCode,
                      java.lang.String errorMsg)
               throws java.io.IOException
Signals an error the the remote host. The method sendError sends a TFTP error packet to the remote host, thus effectively terminating this TFTP request. It must be used to signal any error condition found by the application logic or just to abort the request.

To signal an error the application must provide a numeric error code and a non-null (although it can be empty) error message. The class TftpErrorException defines convenient constants for the standard TFTP error codes.

The method sendError can be called after receiveing a request from a TFTP client (after getting a request with getRequest(int) or getRequest()) or after establishing a connection with a TFTP server (after calling one of the getInputStream() or getOutputStream() methods). After calling sendError no further I/O must be made on the InputStream and OutputStream objects returned by the methods getInputStream() and getOutputStream(), respectively.

Parameters:
errorCode - numeric error code (see TftpErrorException)
errorMsg - human readable error message
Throws:
java.io.IOException - if a communication error occurs
java.lang.IllegalArgumentException - if the error code is outside the range from 0 to 65535 or if the error message is null
java.lang.IllegalStateException - if the host were not specified

Copyright © 2004 LCM Software
All rights reserved