he design of J2ME provides a flexible architecture that allows additional APIs to extend the application specifications such as MIDP and Personal Profile. One such extension is the Wireless Messaging API (WMA) that provides text messaging capabilities from within a J2ME application. In this article I discuss how to integrate messaging protocols such as SMS and CBS into J2ME applications. Although the examples here are shown using MIDP, the same capabilities and principles apply to the Personal Profile space, provided the device supports WMA.

The focus of WMA is around two protocols: Short Message Service (SMS) and Cell Broadcast Service (CBS). The differences between the two are as follows.

Short Message Service (SMS)
SMS provides the ability to send messages between devices. Generally this is referred to as a one-to-one or one-to-few messaging paradigm. The WMA provides full support of two-way messaging, allowing an application to act not only as a client to send messages but also as a server to receive incoming messages.

SMS messages are generally less than 160 characters and contain only simple text. No graphics or other media support is provided by SMS.

The SMS protocol works much in the same way as email. First a message is created and sent to a server. The server then issues a request to find the target device for which the message is intended. If the target device is out of coverage or their device is turned off, the server will hold onto the message until communications can be established with the target device. Once the device can be located, the message it transmitted to the target device. When the target device responds with an acknowledgement of successfully receiving the message, the server is relived of its delivery responsibility and can delete its copy of the message. Figure 1 illustrates how SMS messages are sent between devices.

Figure 1. Message in Motion: An SMS message is routed to the server provided by the SMS service provider. The SMS server then forwards the message on to the target device.

Figure 2. One Way: The broadcast of CBS messages are one way. A CBS message is usually distributed to a localized access point or cell. The message is repeatedly transmitted from the access point to devices within range for a specified time period. Each message is sent on a CBS channel.

Cell Broadcast Service (CBS)
CBS provides the ability to send messages to many devices within a geographical area. The geographical area is usually denoted by a region of cell towers, which are provided with a specific message. These messages are generally repeated at periodic intervals to any devices registered in the cell. By repeating the message for a specified duration, devices just coming into range, or being turned on in the cell, have the opportunity to receive the message, even though the first transmission was missed. Figure 2 illustrates CBS messages being sent to devices.

The content of a CBS message can as large as 1,395 bytes in ether an ASCII or binary format; however, this can vary between network providers. Each message contains the following information, in addition to the message payload:

Table 1. Contents of a CBS message.

Channel Number	This is the category or topic ID indicating the types of messages that will be received. Examples include current weather or stock quotes.
Message Code	This is an ID of the specific message instance.
Update Number	This is a version of a specific message.
Language	This is indicates what language the message content is written in, such as English or French.

A Look at the API
Support for WMA is found in the javax.microedition.messaging package, which includes the interfaces shown in Table 2. The interface hierarchy is shown in Figure 3.

Table 2. Interfaces included in javax.microedition.messaging.

Message	The basic interface for a message. Commonly needed methods are defined such as the ability to get or set the address associated with the message and to retrieve the timestamp of when the message was sent.
BinaryMessage	Extends the Message interface, allowing an application to extract the binary payload of the message.
TextMessage	Extends the Message interface, allowing an application to extract the ASCII payload of the message.
MessageConnection	Supports the functionary for sending and receiving messages based on the underlying protocol.
MessageListener	Allows classes that implement this interface to register with an instance of MessageConnection to be notified when a new message is received.

Figure 3. Selecting Format: TextMessage and BinaryMessage extend the Message interface to provide support for ASCII and binary formatted message payloads.

Show Me the Code
Receiving text messages is pretty much the same, regardless of the protocol being used. Within the WMA, the only difference is that an SMS message listens on a port number where a CBS message listens on a channel ID. However, the way connections are created using the generic connection framework makes both connection protocols look nearly identical. The following illustrates how to create connections for each.

MessageConnection smsListener = (MessageConnection)       Connector.open("sms://:4444");MessageConnection cbsListener = (MessageConnection)     Connector.open("cbs://:3333");

In this example, the CBS connection is created with a channel ID of 3333.

Once an instance of MessageConnection is obtained, all an application needs to do to receive its message is to call the receive() method and wait for another device to send a message. When a message is received, the payload can be extracted and handled as desired. The following example displays the received message to the user in a list.

Figure 4. The WMA Console: The WMA Console selects the default phone number of 5550000 on its first instance.

Message msg = listener.receive();if (msg instanceof TextMessage){  String data = ((TextMessage)msg).getPayloadText();  list.append(data, null);	} else	{  byte[] data = ((BinaryMessage)msg).getPayloadData();  //for simplicity, assume ascii sent in binary format  StringBuffer sb = new StringBuffer();  for (int ccnt = 0; ccnt < data.length; ccnt++) {    sb.append((char)data[ccnt]);  }  list.append(sb.toString(), null);	}

Testing WMA using the Wireless Toolkit
The Wireless Toolkit provides a WMA Console utility for testing WMA-enabled applications. This utility is opened from the KToolbar by selected "File | Utilities" and clicking the "WMA Console" button. The WMA Console is an application that can be used to test sending and receiving SMS and CBS messages.

Figure 5. Sent and Received: A test MIDlet running in the phone emulator receives the SMS message from the Wireless Toolkit WMA Console.

By default, the address (i.e., phone number) for the WMA console is 5550000. Note, however, multiple instances of the console can be opened. Each time the console is opened, the address is incremented by 1. Figure 4 shows the WMA Console when it is first opened.

The code from the message-receiving example can be placed into a MIDlet and tested using the WMA Console. Figure 5 shows the WMA Console sending an SMS message to the MIDlet.

Note that the addresses for the phone emulator and the WMA console are one digit apart. This is due to the Wireless Toolkit automatically assigning addresses to these tools when they are invoked. The address obtained depends on the order the tool is opened.

Sending Messages
Sending messages using WMA applies only to SMS, because the CBS protocol is used by devices only for receiving messages. The following code illustrates sending an SMS message.

Figure 6. Back At Ya: The MIDlet running in the phone emulator sends an SMS message to the WMA Console.

String addr = "sms://5550000:50000";MessageConnection sender =   (MessageConnection)Connector.open(addr);try	{     (TextMessage)sender.newMessage       (MessageConnection.TEXT_MESSAGE);  msg.setPayloadText(messageToSend);  sender.send(msg);} finally   {    sender.close();}

This example first opens a MessageConnection to address 5550000 on port 50000. The port number identifies the port that the target device listens to for the message. Once a connection instance is obtained, a message container can be created by making a request to the newMessage() method of the MessageConnection. Finally, the payload (the content of the message) is set and send() is called to transmit the message. Figure 6 shows a MIDlet sending an SMS message to the WMA Console.

Using the PushRegistry with the WMA
One of the features introduced in WMA 1.1 is support for the PushRegistry of MIDP 2.0. The PushRegistry provides an additional level of networking support that allows a MIDlet to be instantiated to handle in-bound network activity. Combing WMA with the PushRegistry allows a MIDlet to handle SMS and CBS messages even if it is not running when the message is received by the device.

The PushRegistry provides a simple mechanism to link network protocols and ports with a MIDlet suite. Let's suppose a MIDlet provides the ability to receive CBS messages with a channel id of 3333. If the MIDlet is up and running, it can receive these messages without any assistance from the Application Management Software (AMS). However, if the application is not running, the message will be missed. This can be remedied by adding a line to the application descriptor to set up a relationship between any CBS messages of ID 3333 and the MIDlet suite. The following example tells the AMS (using the PushRegistry) to invoke the MIDlet "WmaEg" whenever a CBS message comes in on that channel.

MIDlet-Push-2: cbs://:3333, WmaEg, *

The * indicates that network activity from any IP address can be accepted. Alternatively, this field could be specified to only allow traffic from a specific IP address, such as 10.132.34.7, or from a specific subnet such as 12.173.???.*. The wildcard "?" is used as a single-digit placeholder, where a digit must be supplied in place of the ? wildcard. The "*" wildcard indicates 0 or more characters for this position.

For more details on using the PushRegistry take a look at my article "Push Your MIDlets to do a Lot More with MIDP 2.0 PushRegistry."

PushRegistry and Security
In order to successfully use the PushRegistry to receive WMA messages, permissions must be requested. These requests can be specified in the application descriptor as well.

MIDlet-Permissions: javax.microedition.io.PushRegistry, 
javax.microedition.io.Connector.cbs, javax.wireless.messaging.cbs.receive

The entry above requests permission to use the PushRegistry as well as permissions to obtain a CBS network connection and the ability to receive CBS messages. You also need to use the Wireless Toolkit to designate a user who can configure these settings (see Figure 7. This is accessed by clicking the "Settings" button and selecting the "Permissions" tab.

Figure 7. Setting Permission: Using the Wireless Toolkit to configure permission to use the PushRegistry and CBS messaging.

For more details on setting up MIDP 2.0 security check out my article "Harden Your Wireless Apps with MIDP 2.0 Protection Domains".

Receiving a Pushed CBS Message
The code required to set up a CBS listener is essentially the same as the prior SMS message listener, except that the protocol is CBS.

MessageConnection cbsListener = (MessageConnection)     Connector.open("cbs://:3333”);Message msg = listener.receive();if (msg instanceof TextMessage){  String data = ((TextMessage)msg).getPayloadText();  list.append(data, null);	}

Handling a Pushed Message
If a MIDlet suite is not running and the AMS receives a pushed message on behalf of the MIDlet, the AMS will instantiate the MIDlet suite and invoke the startApp() method. The MIDlet suite then takes over and handles the pushed message. A list of connections with pending data to be handled can be obtained from the PushRegistry in the startApp() method with a call to PushRegistry.listConnections(true). The boolean parameter of "true" indicates the PushRegistry should only return a list of connection strings with pending connection activity. Passing a value of "false" would return any connection strings registered in the PushRegistry.

Deploying the MIDlet Suite
To test this out using the PushRegistry, I will run the MIDlet as an Over-The-Air (OTA) deployed MIDlet suite. This is accomplished by selecting "Projects | Run via OTA" from the Wireless Toolkit. When the phone emulator appears, click the "Apps" button to start the AMS. The only application listed (unless you have previously installed applications) will be "Install Application."

Figure 8. Announcement: CBS message pushed to a MIDlet. The AMS invokes the MIDlet according to the registry entry in the PushRegistry.

Click the "Menu" button and then select the "Launch" option. This will invoke the application installer to "download" the MIDlet and install it into the emulator. This is necessary to test running in the PushRegistry because the AMS must have a registry entry to invoke the MIDlet suite in response to a test message I will send from the WMA Console in a moment.

Running the MIDlet Suite
Once the MIDlet suite is installed it can be run from the emulator as an installed application, just like a user would run the application on a real phone. However, we are more interested in letting the AMS invoke the MIDlet suite in response to a CBS message. So for this test I will just leave the emulator on the first menu without starting the test application. Then I use the WMA console to send a test message. Figure 8 shows the MIDlet receiving the pushed CBS message.

The WMA provides an API for integrating SMS and CBS text and binary messaging protocols into existing and new J2ME applications. Combining WMA 1.1 and MIDP 2.0 provides the powerful capability of using the PushRegistry to better connect a message with its intended recipient.