Datagram

The DataInput and DataOutput interfaces are extended by this interface to provide a simple way to read and write binary data in and out of the datagram buffer. An additional function reset() may be called to reset the read/write point to the beginning of the buffer.

It should be noted that in the interests of reducing space and speed concerns, these mechanisms are very simple. In order to use them correctly the following restrictions should be observed:

1) The use of the standard DataInput and DataOutput interfaces is done in order to provide a familiar API for reading and writing data into and out of a Datagram buffer. It should be understood however that this is not an API to a Java stream and does not exhibit all of the features normally associated with one. The most important difference here is that a Java stream is either an InputStream or an OutputStream. The interface presented here is, essentially, both at the same time. As the datagram object does not have a mode for reading and writing, it is necessary for the application programmer to realize that no automatic detection of the wrong mode usage can be done.

2) The DataInput and DataOutput interfaces will not work with any arbitrary settings of the Datagram state variables. The main restriction here is that the offset state variable must at all times be zero. Datagrams may be used in the normal way where the offset is non-zero but when this is done the DataInput and DataOutput interfaces cannot be used.

3) The DataInput and DataOutput read() and write() functions work by using an invisible state variable of the Datagram object. Before any data is read from or written to the datagram buffer, this state variable must be zeroed using the reset() function. This variable is not the offset state variable but an additional state variable used only for the read() and write() functions.

4) Before data is to be received into the datagram's buffer, the offset state variable and the length state variable must first be set up to the part of the buffer the data should be written to. If the intention is to use the read() functions, the offset must be zero. After receive() is called, the data can be read from the buffer using the read() functions until an EOF condition is found. This will occur when the number of characters represented by the length parameter have been read.

5) To write data into the buffer prior to a send() operation, the reset() function should first be called. This will zero the read/write pointer along with the offset and length parameters of the Datagram object. Then the data can be written using the write() functions. When this process is complete, the length state variable will be set to the correct value for the send() function of the datagram's connection, and so the send operation can take place. An IndexOutOfBoundsException will be thrown if the number of characters written exceeds the size of the buffer.