javax.microedition.io DatagramConnection

javax.microedition.io
DatagramConnection

Declaration
public interface DatagramConnection extends Connection
All Superinterfaces: Connection
Description
This interface defines the capabilities that a datagram connection must have.
Reminder: Since the CLDC Specification does not define any actual network protocol implementations, the
syntax for datagram addressing is not defined in the CLDC Specification. Rather, syntax definition takes place
at the level of J2ME profiles such as MIDP.
In the sample implementation that is provided as part of the CLDC reference implementation, the following
addressing scheme is used:
The parameter string describing the target of a connection in the CLDC reference implementation takes the
following form:
{protocol}://[{host}]:[{port}]
A datagram connection can be opened in a “client” mode or “server” mode. If the “//{host}” part is missing then
the connection is opened as a “server” (by “server”, we mean that a client application initiates communication).
When the “//{host}” part is specified, the connection is opened as a “client”.
Examples:
A datagram connection for accepting datagrams
datagram://:1234
A datagram connection for sending to a server:
datagram://123.456.789.12:1234
Note that the port number in “server mode” (unspecified host name) is that of the receiving port. The port
number in “client mode” (host name specified) is that of the target port. The reply-to port in both cases is never
unspecified. In “server mode”, the same port number is used for both receiving and sending. In “client mode”,
the reply-to port is always dynamically allocated.
Also note that the allocation of datagram objects is done in a more abstract way than in Java 2 Standard Edition
(J2SE). Instead of providing a concrete DatagramPacket class, an abstract Datagram interface is
provided. This is to allow a single platform to support several different datagram interfaces simultaneously.
Datagram objects must be allocated by calling the newDatagram methods of the DatagramConnection
object. The resulting object is defined using another interface type called
javax.microedition.io.Datagram.

Member Summary

int getMaximumLength()
int getNominalLength()
Datagram newDatagram(byte[] buf, int size)
Datagram newDatagram(byte[] buf, int size, java.lang.String addr)
Datagram newDatagram(int size)
Datagram newDatagram(int size, java.lang.String addr)
void receive(Datagram dgram)
void send(Datagram dgram)



Methods inherited from interface Connection
close()



Methods
getMaximumLength()
Declaration:
public int getMaximumLength()
throws IOException
Description:
Get the maximum length a datagram can be. Maximum length determines the maximum size of the
datagram that can be created using the newDatagram method, and the maximum size of the datagram that
can be sent or received.
Returns: The maximum length of a datagram.
Throws:
java.io.IOException - If an I/O error occurs.
getNominalLength()
Declaration:
public int getNominalLength()
throws IOException
Description:
Get the nominal length of a datagram. Nominal length refers to the size of the datagram that is stored into
the data buffer. Nominal length may be equal or less than the maximum length of the datagram.
Returns: The nominal length of a datagram.
Throws:
java.io.IOException - If an I/O error occurs.



send(Datagram)
Declaration:
public void send(javax.microedition.io.Datagram dgram)
throws IOException
Description:
Send a datagram. The Datagram object includes the information indicating the data to be sent, its length,
and the address of the receiver. The method sends length bytes starting at the current offset of the
Datagram object, where length and offset are internal state variables of the Datagram object.
Parameters:
dgram - A datagram.
Throws:
java.io.IOException - If an I/O error occurs.
java.io.InterruptedIOException - Timeout or interrupt occurred.
receive(Datagram)
Declaration:
public void receive(javax.microedition.io.Datagram dgram)
throws IOException
Description:
Receive a datagram. When this method returns, the internal buffer in the Datagram object is filled with
the data received, starting at the location determined by the offset state variable, and the data is ready to
be read using the methods of the DataInput interface.
This method blocks until a datagram is received. The internal length state variable in the Datagram
object contains the length of the received datagram. If the received data is longer than the length of the
internal buffer minus offset, data is truncated.
This method does not change the internal read/write state variable of the Datagram object. Use method
Datagram.reset to change the pointer before reading if necessary.
Parameters:
dgram - A datagram.
Throws:
java.io.IOException - If an I/O error occurs.
java.io.InterruptedIOException - Timeout or interrupt occurred.
newDatagram(int)
Declaration:
public javax.microedition.io.Datagram newDatagram(int size)
throws IOException
Description:
Create a new datagram object.
Parameters:
size - The size of the buffer needed for the datagram
Returns: A new datagram
Throws:
java.io.IOException - If an I/O error occurs.



newDatagram(int, String)
322
java.lang.IllegalArgumentException - if the size is negative or larger than the maximum
size
newDatagram(int, String)
Declaration:
public javax.microedition.io.Datagram newDatagram(int size, java.lang.String addr)
throws IOException
Description:
Create a new datagram object.
Parameters:
size - The size of the buffer needed for the datagram
addr - The I/O address to which the datagram will be sent
Returns: A new datagram
Throws:
java.io.IOException - If an I/O error occurs.
java.lang.IllegalArgumentException - if the size is negative or larger than the maximum
size, or if the address parameter is invalid
newDatagram(byte[], int)
Declaration:
public javax.microedition.io.Datagram newDatagram(byte[] buf, int size)
throws IOException
Description:
Create a new datagram object.
Parameters:
buf - The buffer to be used for the datagram
size - The size of the buffer needed for the datagram
Returns: A new datagram
Throws:
java.io.IOException - If an I/O error occurs.
java.lang.IllegalArgumentException - if the size is negative or larger than the maximum
size or the given buffer’s length, or if the buffer parameter is invalid
newDatagram(byte[], int, String)
Declaration:
public javax.microedition.io.Datagram newDatagram(byte[] buf, int size,
java.lang.String addr)
throws IOException
Description:
Make a new datagram object.
Parameters:
buf - The buffer to be used for the datagram
size - The size of the buffer needed for the datagram



addr - The I/O address to which the datagram will be sent
Returns: A new datagram
Throws:
java.io.IOException - If an I/O error occurs.
java.lang.IllegalArgumentException - if the size is negative or larger than the maximum
size or the given buffer’s length, or if the address or buffer parameter is invalid