This class defines an abstract interface for datagram packets.
The implementations of this interface hold data to be
sent or received from a DatagramConnection object.
Since this is an interface class, the internal structure
of the datagram packets is not defined here. However, it is
assumed that each implementation of this interface will
provide the following fields / state variables (the actual
implementation and the names of these fields may vary):
- buffer: the internal buffer in which data is stored
- offset: the read/write offset for the internal buffer
- length: the length of the data in datagram packet
- address: the destination or source address
- read/write pointer: a pointer that is added to the
offset to point to the current data location during a
read or write operation
Reading and Writing
The Datagram interface extends interfaces
DataInput and DataOutput in order
to provide a simple way to read and write binary data in and out of
the datagram buffer instead of using getData and
setData methods. Writing automatically increments
length and reading will continue while the read/write pointer
is less than length. Before any writing is done reset must be called.
If setData() is to be used when reading or writing, any value
for the offset parameter other than 0 is not supported.
For example to write to datagram:
datagram = connection.newDatagram(max);
// Reset prepares the datagram for writing new message.
datagram.reset();
// writeUTF automatically increases the datagram length.
datagram.writeUTF("hello world");
connection.send(datagram);
For example to read from a datagram (single use only):
datagram = connection.newDatagram(max);
connection.receive(datagram);
message = datagram.readUTF();
Reusing Datagrams
It should be noted the length above is returned
from getLength and can have different meanings at different
times. When sending length is the number of bytes to send. Before
receiving length is the maximum number of bytes to receive.
After receiving length is the number of bytes that were received.
So when reusing a datagram to receive after sending or receiving, length
must be set back to the maximum using setLength.
datagram = connection.newDatagram(max);
while (notDone) {
// The last receive in the loop changed the length
// so put it back to the maximum length.
datagram.setLength(max);
connection.receive(datagram);
data = datagram.getData();
bytesReceived = datagram.getLength();
// process datagram ...
}
When reading instead of using getData the reset
method must be used.
datagram = connection.newDatagram(max);
while (notDone) {
// The last read in the loop changed the read pointer
// so reset the pointer.
datagram.reset();
datagram.setLength(max);
connection.receive(datagram);
message = datagram.readUTF(message);
// process message ...
}
For example to reread a datagram:
connection.receive(datagram);
message = datagram.readUTF(message);
len = datagram.getLength();
datagram.reset();
datagram.setLength(len);
copy = datagram.readUTF(message);
version:
12/17/01 (CLDC 1.1)
since:
CLDC 1.0 |