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.