Download

17.1 Alarm-Based MIDlet Launch

It can often be useful for a MIDlet to be launched at a preset time to provide information to the user in a timely fashion. For example, a MIDlet that sells movie tickets might set an alarm to warn the ticket-holding user about the impending start time of the movie.

To use alarm-based notification, a MIDlet calls the PushRegistry.registerAlarm method. The MIDlet must supply the name of the MIDlet to launch (it must be a MIDlet in the same MIDlet suite) and a launch time. The named MIDlet must have been registered in the JAD file or the JAR manifest with a MIDlet-n attribute. Providing a launch time of zero removes any alarm.

The push registry supports one alarm per MIDlet. If a registration occurs for a MIDlet that already has an alarm set, the new registration is used. The PushRegistry.registerAlarm method returns the old registration time in milliseconds since January 1, 1970, 00:00:00 GMT. Note that the time returned could be in the past. It returns zero for the MIDlet's first alarm registration.

Errors may occur during alarm registration. If the runtime system does not support alarm-based application launch, the registerAlarm method throws a ConnectionNotFoundException. If the MIDlet class name provided is null or is not in a MIDlet-n attribute in the MIDlet suite's JAR manifest or JAD file, the registerAlarm method throws a ClassNotFoundException. If the MIDlet does not have permission to register an alarm, the registerAlarm method throws a SecurityException. (See Section 17.5, "Security of the Push Registry," for more information.)

A device could be unable to launch the MIDlet for the alarm. For example, a MIDlet cannot be launched if the device is off at the wake-up time. Similarly, the MIDlet cannot be launched if it is running at the wake-up time. As a result, MIDlets should be written to check the current time against the scheduled wake-up time. They can use class java.util.TimerTask to manage time-based events while they are running. (See Section 20.1, "Timer Support," for more information.)

As a general rule, do not use the alarm to periodically launch a MIDlet to check for new information. Polling is an inefficient use of phone and network resources. It can run down the battery if it activates the device too often and can incur extra network-usage costs, while providing little or no value to the consumer. Instead, use push notification: have the network service send messages to the MIDlet when new information should be presented to the user.

If push notification cannot be used (for example, if the device does not support it), MIDlets that use alarm-based notification should be written to collapse or compress any duplicate events for MIDlets in the suite. This will help to avoid the usability problems associated with starting the MIDlet too frequently.