|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
@TransactionType(value=NOT_SUPPORTED) public interface Datagram
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):
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);
Method Summary | |
---|---|
String |
getAddress()
Get the address of the datagram. |
byte[] |
getData()
Get the contents of the data buffer. |
int |
getLength()
Get the length of the datagram. |
int |
getOffset()
Get the offset. |
void |
reset()
Zero the read/write pointer as well as the
offset and length state variables. |
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 state variables. |
void |
setLength(int len)
Set the length state variable. |
Methods inherited from interface java.io.DataInput |
---|
readBoolean, readByte, readChar, readFully, readFully, readInt, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, skipBytes |
Methods inherited from interface java.io.DataOutput |
---|
write, write, write, writeBoolean, writeByte, writeChar, writeChars, writeInt, writeLong, writeShort, writeUTF |
Method Detail |
---|
String getAddress()
setAddress(java.lang.String)
byte[] getData()
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.
setData(byte[], int, int)
int getLength()
setLength(int)
int getOffset()
void setAddress(String addr) throws IOException
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.
addr
- the new target address as a URL
IllegalArgumentException
- if the address is not valid
IOException
- if a some kind of I/O error occursgetAddress()
void setAddress(Datagram reference)
reference
- to the datagram whose address will be copied as the new target
address for this datagram.
IllegalArgumentException
- if the address is not validgetAddress()
void setLength(int len)
length
state variable.
len
- the new length of the datagram
IllegalArgumentException
- if the length or length plus offset fall outside the
buffergetLength()
void setData(byte[] buffer, int offset, int len)
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.
buffer
- the data bufferoffset
- the offset into the data bufferlen
- the length of the data in the buffer
IllegalArgumentException
- if the length or offset or offset plus length fall outside
the buffer, or if the buffer parameter is invalidgetData()
void reset()
read/write pointer
as well as the
offset
and length
state variables.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |