Use Push Registry for automatically Launch a MIDlet

Original message from: http://developers.sun.com/mobility/midp/questions/pushregistry/

If you want to launch MIDlet automatically, you can use Push Registry.

How to do ?

The PushRegistry class supports a "push" model of content distribution. Enabling a MIDlet to launch in response to an incoming connection or at a scheduled time makes whole new classes of services possible.

Specifying a PushRegistry entry requires four items:

* The MIDlet to be launched, specified using the MIDlet- attribute.

* If the MIDlet suite is signed, a Permissions request, using the MIDlet-Permissions attribute. The request must include at least the javax.microedition.io.PushRegistry method.

* An inbound connection URL, required by the Connector.open() method.

* A filter for inbound connections. The format of the filter is protocol-specific, but the filter "*" matches any string, and "?" matches any single character.

A PushRegistry entry can be specified in either a static or dynamic form.

A static PushRegistry entry is specified in the Java Application Descriptor (JAD) file, the manifest file, or both. The MIDlet, once installed, will always respond to the specified incoming connection. Add the MIDlet, Push Registry, and Permissions attributes to the JAD or manifest, as in this example JAD file:

MIDlet-1 : CalPushHandler
MIDlet-Permissions : javax.microedition.io.PushRegistry,
javax.microedition.io.Connector.socket
MIDlet-Push-1 : socket://:5012, CalPushHandler, *


These settings will cause the MIDlet CalPushHandler to launch in response to an incoming connection request on port 5012.

A dynamic PushRegistry entry is much the same as a static entry except that you use the PushRegistry.registerConnection() method to specify the Push Entry instead of using the MIDlet-Push- attribute. The MIDlet- attribute is still required in the JAD or manifest, as is the MIDlet-Permissions attribute, in the case of a signed MIDlet suite. A dynamic entry can be enabled (and disabled using the PushRegistry.unregisterConnection() method) after MIDlet suite installation. An example JAD file would contain:

MIDlet-1 : CalPushHandler
MIDlet-Permissions : javax.microedition.io.PushRegistry,
javax.microedition.io.Connector.socket


The MIDlet source code would include:

...
import javax.microedtion.io.PushRegistry;
...

String connURL = "socket://:5012";
String MIDletStr = "CalPushHandler";
String FilterStr = "*";

try {
PushRegistry.registerConnection(connURL,
MIDletStr, FilterStr);
} catch ( ClassNotFoundException cnf ) {
...
} catch ( IOException ioe ) {
...
}
...


Using Alarms to Launch MIDlets

The PushRegistry.registerAlarm() method sets up a MIDlet to launch at a scheduled time. It's similar to the UNIX at(1) facility. The method requires a MIDlet within the current suite to launch, along with a time. Specify the MIDlet as a String and the time as a java.util.Date. A sample follows.

In the JAD or manifest file, insert:

MIDlet-1 : AlarmMIDlet
MIDlet-Permissions : javax.microedition.io.PushRegistr


In the MIDlet source code include:

...
import javax.microedtion.io.PushRegistry;
...
long prevalarm;
String MIDletname = "AlarmMIDlet";
Date nexttime = new java.util.Date() + 60000;

prevalarm = PushRegistry.registerAlarm( MIDletname, nexttime );
...


The MIDP 2.0 specification limits the number of alarms per MIDlet in a suite to one.

Note that the spec doesn't require implementations to support these PushRegistry features. If they're not supported, a ConnectionNotFoundException exception will be thrown.

An Example

The sample MIDlet suite illustrates use of a static PushRegistry entry and of the PushRegistry.registerAlarm() method. Note that the MIDlet suite does not include any UI components.

The MIDlet suite contains two MIDlets and one other class. The PushMIDlet provides a time-of-day (TOD) service (see: Internet Engineering Task Force RFC 867) using the DayTimeServer class. DayTimeServer implements the Runnable interface, executing the TOD service in a separate thread. DayTimeServer opens the server connection, accepts the incoming connection (the event that initiated the MIDlet launch in the first place), responds to the client with the current time as a string, closes the connections, and exits. All in all, not very exciting, but illustrative and extensible.

The PushMIDlet also registers the AlarmMIDlet for execution 60 seconds after the PushMIDlet is launched. The AlarmMIDlet merely re-schedules itself using PushRegistry.registerAlarm(). The result is recurring launch of the MIDlet, similar to the UNIX cron(1M) facility. The AlarmMIDlet can easily be extended to include more interesting activities to be executed periodically.

Conclusion

The two new MIDlet-launching mechanisms that the MIDP 2.0 PuhRegistry class provides make possible the creation of more content-rich services.