javax.microedition.io
Interface Datagram

All Superinterfaces:

DataInput, DataOutput

All Known Implementing Classes:

Radiogram

public interface Datagram
extends DataInput, DataOutput

This is the generic datagram interface. It represents an object that will act as the holder of data to be sent or received from a datagram connection.

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.

Version:

1.2 1/17/2000

Author:

Brian Modra, Nik Shaylor

Method Summary

String	getAddress() Get the address in the datagram.
byte[]	getData() Get the buffer.
int	getLength() Get the length.
int	getOffset() Get the offset.
void	reset() Zero the read/write pointer as well as the offset and length parameters.
void	setAddress(Datagram reference) Set datagram address, copying the address from another datagram.
void	setAddress(String addr) Set datagram address.
void	setData(byte[] buffer, int offset, int len) Set the buffer, offset and length.
void	setLength(int len) Set the length.

Methods inherited from interface java.io.DataInput

readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, skipBytes

Methods inherited from interface java.io.DataOutput

write, write, write, writeBoolean, writeByte, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF

Method Detail

getAddress

String getAddress()

Get the address in the datagram.

Returns:

the address in string form, or null if no address was set

See Also:

setAddress(java.lang.String)

getData

byte[] getData()

Get the buffer.

Returns:

the data buffer

See Also:

setData(byte[], int, int)

getLength

int getLength()

Get the length.

Returns:

the length of the data

See Also:

setLength(int)

getOffset

int getOffset()

Get the offset.

Returns:

the offset into the data buffer

reset

void reset()

Zero the read/write pointer as well as the offset and length parameters.

setAddress

void setAddress(String addr)
                throws IOException

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:

IllegalArgumentException - if the address is not valid

IOException - if a some kind of I/O error occurs

See Also:

getAddress()

setAddress

void setAddress(Datagram reference)

Set datagram address, copying the address from another datagram.

Parameters:

reference - the datagram who's address will be copied as the new target address for this datagram.

Throws:

IllegalArgumentException - if the address is not valid

See Also:

getAddress()

setData

void setData(byte[] buffer,
             int offset,
             int len)

Set the buffer, offset and length.

Parameters:

buffer - the data buffer

offset - the offset into the data buffer

len - the length of the data in the buffer

Throws:

IllegalArgumentException - if the length or offset fall outside the buffer

See Also:

getData()

setLength

void setLength(int len)

Set the length.

Parameters:

len - the new length of the data

Throws:

IllegalArgumentException - if the length is negative or larger than the buffer

See Also:

getLength()