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.
Sections
