Programming Wireless Devices with the Java2 Platform

19.3 Over-the-Air User-Initiated Provisioning

MIDP devices without installed MIDlets would not be all that useful. Granted, a device may provide a way to download MIDlets through serial cable or similar mechanism, which would enable the installation of MIDlets. However, one of the biggest advantages of recent devices is the availability of wireless data connectivity, whereby the device can connect with Internet servers and services to download MIDlets over-the-air (OTA). In this way, the user can have access to new MIDlets while in the airport, train station, at a friend's house, in a meeting, or generally anywhere where wireless coverage is available.

In the MIDP Specification version 2.0, the OTA download specification is based on the HTTP protocol.^[3] While the most common way a user will discover MIDlet suites for downloading will be through the WWW, WAP, or iMode browser resident on the device, other solutions are possible. For the specification and this book, we will use the more generic term discovery agent (DA) to indicate the application used for discovering and downloading a MIDlet suite.

^[3] The term HTTP protocol is used generically in this chapter to mean HTTP and HTTPS, as well as the WAP protocol (WSP) with the http:// schema.

For the sake of simplicity in the rest of this discussion, we will ignore the intermediate wireless base stations, network nodes, and other network components, and consider the OTA transaction as a direct connection between the mobile device and a server.

A typical transaction is illustrated in the event transition diagram in Figure 19.2, and it consists of the following steps:

19.3.1 MIDlet Suite Updates

If the MIDlet suite being requested for installation is already installed on the device (either the same version or a different version), the device treats this as a request to update the MIDlet suite. In this case the device will allow the user to obtain information about the MIDlet suite(s) on the device and determine what version of this MIDlet suite is installed, and it will notify the user if the MIDlet suite is a newer, older, or the same version of an existing MIDlet suite. It will then get confirmation from the user before proceeding.

The RMS record stores of a MIDlet suite being updated will be managed as follows:

• If the cryptographic signer of the new MIDlet suite and the original MIDlet suite are identical, then the RMS record stores will be retained and made available to the new MIDlet suite.

• If the scheme, host, and path of the URL that the new Application Descriptor is downloaded from is identical to the scheme, host, and path of the URL the original Application Descriptor was downloaded from, then the RMS will be retained and made available to the new MIDlet suite.

• If the scheme, host, and path of the URL that the new MIDlet suite JAR is downloaded from is identical to the scheme, host, and path of the URL the original MIDlet suite JAR was downloaded from, then the RMS will be retained and made available to the new MIDlet suite.

• If all of the above statements are false, then the device will ask the user whether the data from the original MIDlet suite should be retained and made available to the new MIDlet suite.

An unsigned MIDlet will not be allowed to update a signed MIDlet suite. The format, contents, and versioning of the record stores is the responsibility of the MIDlet suite. The user-granted permissions given to the original MIDlet suite will usually also be given to the new MIDlet suite, if they are in the security domain of the new MIDlet suite.

19.3.2 MIDlet Suite Removal

When a MIDlet suite is to be removed from the device, the user will usually be prompted to confirm that the MIDlet suite may be removed. The device will usually warn the user of any special circumstances that arise during the deletion of the MIDlet suite. For example, the MIDlet suite could contain multiple MIDlets, and the user should be made aware that all of the MIDlets and associated RMS record stores are being removed.

If the Application Descriptor includes the attribute MIDlet-Delete-Confirm, its value will usually be included in the prompt. This will allow the MIDlet suite provider to highlight any specific conditions that might arise if the MIDlet suite were to be removed.

19.3.3 Installation and Deletion Status Reports

The success or failure of the installation, upgrade, or deletion of a MIDlet suite is of interest to the service providing the MIDlet suite. The service can specify URLs in the Application Descriptor for reporting installation and deletion status. If the device cannot send the installation status report, the requested action will still be completed. For example, if the device cannot send the installation status report to the MIDlet-Install-Notify URL, the MIDlet suite will still be enabled, and the user will be allowed to use it. Likewise, if the device cannot send the deletion status report to the MIDlet-Delete-Notify URL, the MIDlet suite will still be deleted.

The operation status is reported by means of an HTTP POST to the URL specified in the MIDlet-Install-Notify attribute for installations, and by use of the MIDlet-Delete-Notify attribute for deletions. The only protocol that devices must support is "http://". Other protocols might be ignored by the device.

The content of the body of the POST request will include a status code and status message on the first line. See Table 19.2 for a list of valid codes and status messages.

In the case of a deletion status report, a notification with status code 912 is sent when the MIDlet is deleted.

In response to a status report, the server will reply with the standard HTTP "200 OK" response. No content should be returned to the device and, if any is sent, it will be ignored by the device.

For installations, if the status report cannot be sent, or if the server reply is not received, the installation status report might be sent again (as described above) each time a MIDlet in this suite is executed and the device has data network connectivity. This is optional behavior and would improve the likelihood of the status report being successfully sent, but each retry would likely result in a charge to the user's bill. The MIDlet suite will be made available for use, whether or not the installation status report has been successfully sent and the acknowledgement has been received.

For deletions, an attempt to send the status report will not be made immediately, but instead made the next time either an OTA installation is performed or an installation status report is being sent. This will improve the likelihood of the status report being successfully sent and will minimize confusion by the user when they see network activity. If the status report cannot be sent, or if the server reply is not received, the deletion status report may be sent again (as described above) each time an OTA installation is performed or an installation status report is being sent. The number of retries attempted should be kept small since each one may result in a charge to the user's bill. The MIDlet suite will be removed from memory whether or not the installation status report has been successfully sent and the acknowledgement has been received.

19.3.4 Installation Status Codes and Messages

Table 19.2 summarizes the status codes to be sent from client to server to report the status of installation.

Table 19.2. MIDlet status codes and status messages

Status Code	Status Message
900	Success
901	Insufficient memory
902	User cancelled
903	Loss of service
904	JAR size mismatch
905	Attribute mismatch
906	Invalid descriptor
907	Invalid JAR
908	Incompatible configuration or profile
909	Application authentication failure
910	Application authorization failure
911	Push registration failure
912	Deletion notification