javax.microedition.io Datagram

javax.microedition.io
Datagram

Declaration
public interface Datagram extends java.io.DataInput, java.io.DataOutput
All Superinterfaces: java.io.DataInput, java.io.DataOutput
Description
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);



Methods
java.lang.String getAddress()
byte[] getData()
int getLength()
int getOffset()
void reset()
void setAddress(Datagram reference)
void setAddress(java.lang.String addr)
void setData(byte[] buffer, int offset, int len)
void setLength(int len)



Methods inherited from interface DataInput
readBoolean(), readByte(), readChar(), readDouble(), readFloat(), readFully(byte[],
int, int), readFully(byte[], int, int), readInt(), readLong(), readShort(),
readUTF(), readUnsignedByte(), readUnsignedShort(), skipBytes(int)



Methods inherited from interface DataOutput
write(byte[], int, int), write(byte[], int, int), write(byte[], int, int),
writeBoolean(boolean), writeByte(int), writeChar(int), writeChars(String),
writeDouble(double), writeFloat(float), writeInt(int), writeLong(long),
writeShort(int), writeUTF(String)



Methods
getAddress()
Declaration:
public java.lang.String getAddress()
Description:
Get the address of the datagram.
Returns: the address in string form, or null if no address was set
See Also: setAddress(String)
getData()
Declaration:
public byte[] getData()
Description:
Get the contents of the data buffer.
Depending on the implementation, this operation may return the internal buffer or a copy of it. However, the
user must not assume that the contents of the internal data buffer can be manipulated by modifying the data
returned by this operation. Rather, the setData operation should be used for changing the contents of the
internal buffer.
Returns: the data buffer as a byte array
See Also: setData(byte[], int, int)
getLength()
Declaration:
public int getLength()
Description:
Get the length of the datagram.
Returns: the length state variable
See Also: setLength(int)
getOffset()
Declaration:
public int getOffset()



Description:
Get the offset.
Returns: the offset state variable
setAddress(String)
Declaration:
public void setAddress(java.lang.String addr)
throws IOException
Description:
Set datagram address.
The actual addressing scheme is implementation-dependent. Please read the general comments on datagram
addressing in DatagramConnection.java.
Note that if the address of a datagram is not specified, then it defaults to that of the connection.
Parameters:
addr - the new target address as a URL
Throws:
java.lang.IllegalArgumentException - if the address is not valid
java.io.IOException - if a some kind of I/O error occurs
See Also: getAddress()
setAddress(Datagram)
Declaration:
public void setAddress(javax.microedition.io.Datagram reference)
Description:
Set datagram address, copying the address from another datagram.
Parameters:
reference - to the datagram whose address will be copied as the new target address for this
datagram.
Throws:
java.lang.IllegalArgumentException - if the address is not valid
See Also: getAddress()
setLength(int)
Declaration:
public void setLength(int len)
Description:
Set the length state variable.
Parameters:
len - the new length of the datagram
Throws:
java.lang.IllegalArgumentException - if the length or length plus offset fall outside the
buffer
See Also: getLength()


setData(byte[], int, int)
318
setData(byte[], int, int)
Declaration:
public void setData(byte[] buffer, int offset, int len)
Description:
Set the buffer, offset and length state variables. Depending on the implementation, this operation
may copy the buffer or just set the state variable buffer to the value of the buffer argument. However,
the user must not assume that the contents of the internal data buffer can be manipulated by modifying the
buffer passed on to this operation.
Parameters:
buffer - the data buffer
offset - the offset into the data buffer
len - the length of the data in the buffer
Throws:
java.lang.IllegalArgumentException - if the length or offset or offset plus length fall
outside the buffer, or if the buffer parameter is invalid
See Also: getData()
reset()
Declaration:
public void reset()
Description:
Zero the read/write pointer as well as the offset and length state variables.