It is quite possible for someone to have worked with Java for some time without ever needing to understand or use datagrams. For mobile devices, however, datagrams offer some advantages in that they are rather lightweight when compared to TCP-based connections such as sockets. User Datagram Protocol, UDP, is one of the more common datagram protocols. However, because most datagram protocols follow the same basic principals as to their usage, the GCF is able to support datagrams generically.

Datagrams are based on a connection-less paradigm, which means that a conversation is not established between two systems. Instead, datagrams are blindly transmitted across a network connection. To transmit a datagram from one system to another, an application creates a datagram and sends it to the intended target. This is a rather simple process in J2ME. However, there is a caveat to using datagrams in that they offer no guarantee or acknowledgement as to whether the datagram actually reached the intended recipient. As a result, a datagram implementation must either not care if the recipient actually receives the data 100 percent of the time, or an acknowledgement/handshake must be implemented manually by the application.

Using Datagrams
The following example shows how to create a datagram and send it to a specific IP address.

try	{
  DatagramConnection dgc = (DatagramConnection)
    Connector.open("datagram://localhost:9001");
  try {
    byte[] payload = "Test Message".getBytes();
    Datagram datagram = 
      dgc.newDatagram(payload, payload.length);
    dgc.send(datagram);
  } finally {
      dgc.close();
  }
} catch (IOException x) {
  x.printStackTrace();
}

In this example, a MIDlet creates a Datagram containing the text "Hello from a Datagram" and sends it to an application listening for datagrams on the local machine on port 9001. This example will execute just fine even if there is no application running to receive the datagram, thus demonstrating the connection-less nature of datagrams. The sender has no indication that the datagram was consumed by the target system.

Next I show how an application might receive the datagram sent by the previous code snippet.

try {
  DatagramConnection dgc = (DatagramConnection) 
    Connector.open("datagram://:9001");
  try {
    int size = 100;
    Datagram datagram = dgc.newDatagram(size);
    dgc.receive(datagram);
    System.out.println(
      new String(datagram.getData()).trim());
  } finally {
      dgc.close();
  }
} catch (IOException x){
  x.printStackTrace();
}

In the receive example, a datagram connection is established on port 9001. A datagram is created with a size of 100 bytes; if a received datagram contains more than 100 bytes, any data beyond the 100-byte mark is ignored. Once the datagram is created the receive() method is called, putting the thread in a wait state until a datagram is received. When a datagram is received, the payload is extracted from the datagram container and printed to the console.

In order to run the send and the receive examples, two instances of a MIDlet can be run from the Wireless Toolkit, one to perform the receive and one to perform the send.