Appendix C. Automatic launch

If the Mobile Sensor API is implemented on top of the MIDP 2.0, the PushRegistry is used for registering applications for automatic launch. The PushRegistry maintains a list of registrations. When the application is registered, the sensor URL containing the conditions for launch is specified together with the application to be launched. The application management software (AMS) monitors the defined sensors. When the sensor becomes available or one of the monitored conditions is met, the AMS finds the application to be woken up and launches it.

The AMS MUST store the data value that caused the automatic launch of the application when the monitored condition was met, as well as the met condition. The validity, uncertainty and timestamp information MUST also be stored. When availability is monitored, there is no special requirement to store any values.

The automatic launch by push mechanism may not always mean that the application is immediately started. The user may get a prompt indicating that the application should be launched and the actual launch will happen only once the user confirms to accept it. Whether the user gets a prompt or not depends on the security policy for push. Therefore, the delay between the match in the monitoring and the actual launch of the application may be considerably long. The data values in between the met condition and the first data retrieval method call MUST be discarded. The AMS MUST supply the data value that caused the application launch as a ConditionListener.conditionMet() notification to the application when the application opens the SensorConnection and registers itself as the ConditionListener to monitor the data. The registration is done in the special manner, for example:

    channel.addCondition(this, null);

This will cause the pending conditionMet() notification to be sent to the ConditionListener whatever is the channel or the condition met. Note that the conditionMet() notification will be sent only once when the addCondition() method with the null condition value is called for the first time. After the connection to the sensor is closed, the information is deleted.

Sensor URL scheme for push

The sensor URL scheme for the PushRegistry defined in the description of the SensorConnection class reflects the two ways of sensor push:

Availability-based push. When, for example, the wired sensor is plugged in or the sensor working over Bluetooth is coming within the proximity of the device, the application is launched. No conditions are defined.
Condition-based push. There are conditions defined in the query part of the URL. The conditions are defined separately for each channel. The query part means the part starting from the question mark ("?"). In addition to the availability at least one of the set conditions has to be met for the application to be launched.

Availability-based push

"Being available" means that the sensor can be opened and data values read. By using push mechanism, the sensor application can be launched automatically when the sensor becomes available. Some sensors may not support availability-based push. For example, if you have an embedded sensor that is always available, availability-based push is not supported. Whether the sensor supports availability-based push can be found out with the method SensorInfo.isAvailabilityPushSupported() .

An example of availability-based push is presented below. The MIDlet is registered statically in the JAD:

    MIDlet-Push-1: sensor:humidity,sample.PushApp,*
    MIDlet-Permissions: javax.microedition.io.PushRegistry

The AMS system checks periodically the availability of supported humiditymeters around. When any of these humiditymeters becomes available, the PushApp MIDlet is launched.

Condition-based push

"Meeting conditions" means that measured value meets one of the set conditions. The conditions are set per channel. After one condition of any channel is met, the registered application is launched. The sensor URL scheme for the PushRegistry does not define conditions for channels of an Object data type. Whether a sensor supports condition-based push can be found out with the method SensorInfo.isConditionPushSupported() .

An example of condition-based push is presented below. The MIDlet is registered statically in the JAD:

    MIDlet-Push-1: sensor:RR_interval?channel=RR_interval&limit=240&op=le,
                   sample.PushApp,*
    MIDlet-Permissions: javax.microedition.io.PushRegistry,
		   javax.microedition.sensor.PrivateSensor

The AMS system checks periodically the availability of supported RR_interval sensors around. If a RR_interval sensor is available, then the defined conditions are checked. If any of the conditions is met, the application is launched. In the example above, the measured value being less than or equal to 240 ms causes the application to be launched.

Push support of a sensor

A sensor MAY support either availability-based or condition-based push, or both, or no push at all. The PushRegistry MUST throw a ConnectionNotFoundException for the following reasons:

A sensor matching to the given URL is not found and the device is not capable of supporting sensors of this type.
A sensor is found but it does not support push at all.
A sensor is found but it only supports availability-based push and the URL contains conditions.
A sensor is found but it only supports condition-push and the URL does not contain conditions.

Note that there is also a possibility to register a well formed sensor URL, which is returning a zero-length SensorInfo array when it is given as a parameter to the method SensorManager.findSensors(URL) . The registration is possible if this type of a sensor is known to be supported in the future.

If there are several sensors matching to the URL a ConnectionNotFoundException is not thrown unless none of the sensors can accept the URL.

The same URL can be registed many times to launch different applications. The implementation may be able to provide data to many applications simultanously and this possibility should not be ruled out by accepting the URL only once. This enhances JSR 118 which says:"If two MIDlet suites have a static push connection in common, they cannot be installed together and both function correctly. The end user would typically have to uninstall one before being able to successfully install the other."

Push if only one application can be open at a time

Some devices are only able to support one application being executed at a time. In such devices, if a sensor supports availability-based push, only one URL without conditions can be registered for that sensor. After such URL is registered, attempts to register more URLs MUST cause the registration to fail and an IOException to be thrown.

If a sensor supports condition-based push, it is possible to register multiple URLs containing conditions. In this case the conditions MUST not overlap. If conditions overlap, the registration MUST fail. There MAY be an implementation-dependent maximum for registrations of URLs with conditions. If availability-based and condition-based pushes are both supported, it's not possible to register URLs without conditions after one URL with conditions is registered.

However, if there are several matching sensors, an IOException is thrown only if none of the sensors can accept the URL.

Push if multiple applications can be open simultaneously

Some devices are able to support multiple concurrently executing applications. In such devices, an arbitrary number of applications can be registered per sensor. The implementation SHOULD define a maximum for simultaneous registrations. An IOException is thrown at push registration when the maximum number of registrations has been already reached for all the sensors matching the given URL.

If multiple registrations per sensor are allowed, all the corresponding applications MUST be launched, either when the sensor becomes available or any of the conditions is met. Until the limit of applications to be executed simultaneously is reached, the implementation MAY decide freely the order in which applications are launched.