MIDP Networking and Serial Communications

15.7 UDPDatagramConnection

The UDPDatagramConnection interface extends the interface java.microedition.- io.DatagramConnection to define a UDP datagram connection. (Refer to the documentation of interface DatagramConnection on page 69.) The UDP datagram protocol is defined by the IETF standard RFC768 [reference 1]. The protocol is message-oriented; delivery and duplicate protection are not guaranteed. Applications use UDP datagram connections to exchange messages with minimal overhead, but if ordered reliable delivery of streams of data is required, a SocketConnection is a better choice.

An application opens a UDP datagram connection by calling the Connector.open method. The application must provide a URI string that starts with "datagram://" and is followed by a host name and port number separated by a colon. If the string has neither the host nor port fields, the device allocates an available port. If the connection string is invalid, an IllegalArgumentException is thrown.

1 Getting the Local Address and Port Number

An application can get the local host address and port number for an open connection. (This information is needed primarily for applications that use UDPDatagramConnections to allow clients to send datagrams to a dynamically assigned port.) The getLocalAddress method returns the local IP number to which the socket is bound. Calling the method System.getProperty("microedition.hostname") returns the host name of the device, if it is available. The getLocalPort method returns the local port to which this socket is bound.

If an application sends address and port information to a remote application so that it can connect to the device, the application should try to send the host name of the device. IP addresses can be dynamically assigned, so a remote application with only an IP address will not be able to make contact if the device IP number changes. If a host name is available, sending it would help the remote application be more robust.

2 Datagrams

The UDPDatagramConnection interface inherits methods to create, send, and receive datagrams from the interface javax.microedition.io.DatagramConnection. Once created, a datagram can be used and reused for reading or writing. A Datagram consists of an address and a data buffer. The address is a URL string in the same syntax as described for the method Connector.open. If the datagram will be sent, the application uses the Datagram.setAddress method to assign a destination address. (The address must include both the host and port.) If the Datagram was received, the address contains the source address.

The data buffer is a byte array with an offset and a length. An application can access the byte array either directly or indirectly through the datagram's DataInputStream for reading and DataOutputStream for writing. The datagram's getOffset and setOffset methods are the accessor methods for the offset of the first byte of data. The getLength and setLength methods are the accessor methods for the number of bytes of data in the datagram. The data buffer, offset, and length must be set before the Datagram is sent. Before receiving a Datagram, the buffer, offset, and length must also be set to indicate the bytes available to store the incoming message.

The datagram also has a reset method that is used to initialize the internal state used for reading and writing. Mixing reads, writes, and direct access to the data buffer is not recommended because the interactions between them are complex.

The number of bytes that the UDPDatagramConnection can handle for each send and receive may be limited. The getNominalLength method returns the normal size that the transport can handle in a single packet. The getMaximumLength method returns the upper limit on the size of a datagram. Some transports fragment a large datagram into smaller pieces for transport and reassemble them at the destination.

3 Closing Connections

An application closes a UDP datagram connection with the javax.microedition.io.Connector.close method. The UDPDatagramConnection methods throw an IOException if an application attempts to call the methods after the connection has been closed.

15.7.4 Security of UDPDatagramConnection

Access to datagrams is restricted to prevent unauthorized transmission or reception of data. MIDlet suites needing to use datagrams must request the javax.microedition.io.Connector.datagram permission for Trusted MIDlet suites as described in Section 18.3, "Trusted MIDlet Suite Security Model."

The device may try to authorize the MIDlet when the MIDlet calls the Connector.open method with a valid datagram connection string. If the authorization fails and the MIDlet is not allowed to use the UDP datagram connection API, the Connector.open method throws a java.lang.SecurityException. The device might also check the MIDlet's permission when the MIDlet calls the receive or send methods.

5 Example

Applications can use datagrams to asynchronously send and receive information. The following example uses a thread to receive datagrams of the maximum possible size on a known port and process the messages it receives. When it receives a zero length datagram it closes the connection and terminates.

public void run() {
    UDPDatagramConnection c = null;
    Datagram dgram;
    try {
        // Open the UDP Datagram Connection
        c = (UDPDatagramConnection)
                Connector.open("datagram://:4444");
        int max = c.getMaximumLength();

        // Create a new datagram with a maximum-sized data buffer
        dgram = c.newDatagram(max);
        byte[] buf = dgram.getData();

        // Read in and process datagrams (stop at an empty datagram)
        while (true) {
            dgram.setLength(max);
            c.receive(dgram);
            int len = dgram.getLength();
            if (len == 0) {
                // All done: close and return
                break;
        } else {
            // Process the data
            process(buf, len);
        }
    }
} catch (IOException ex) {
     // handle the exception
} finally {
    // Close the connection
    try {
        c.close();
    } catch (IOException ex) {
    }
}