O'Reilly Book Excerpts: J2ME in a Nutshell

The Mobile Information Device Profile and MIDlets, Part 5

Related Reading J2ME in a Nutshell By Kim Topley Read Online--Safari Search this book on Safari:   Only This Book All of Safari Code Fragments only

by Kim Topley

Editor's note: This is the final excerpt in a series from J2ME in a Nutshell, focusing on the delivery and installation of MIDlets.

Delivery and Installation of MIDlets

The MIDP specification creates the concept of a MIDlet, defines its lifecycle and its execution environment, and specifies the programming interfaces that a MIDlet can expect to be present on any conforming device. However, it currently does not address in any detail how the user should locate MIDlet suites, how MIDlet suites will be installed on a cell phone or a PDA, and what facilities are to be provided to allow the user to select and launch an installed MIDlet or to remove MIDlet suites from the device. These features are not covered in detail in the MIDP specification because they are largely device-specific. Instead, it refers loosely to software that is intended for application delivery and management. The term Application Management Software (AMS) is generally used to describe the software components that take on this responsibility.[1] The MIDP reference implementation provides an example AMS for the benefit of vendors porting the software to their own devices, and both the Wireless Toolkit and the MIDP for PalmOS product have their own AMS implementations, which allow software to be installed from two different sources:

From a local host computer via a dedicated, relatively high speed connection

This mode of operation is particularly suitable for PDAs, which are typically associated with a desktop or laptop computer with which they periodically synchronize. Synchronizing backs up the user's data from the handheld onto the larger system and copies software and data in the other direction, as well. The MIDP for PalmOS implementation is a good example of this, because its AMS allows MIDlet suites to be installed from a host PC during the synchronization process. Once the MIDlets are installed, they can be launched on the PDA in the same way as its native applications. The same application management features are supported for MIDlets, so they appear to be almost the same as native applications.

Over a network to which the device is connected

This is the most common way in which MIDlets are downloaded to cell phones and similar wireless devices, although it is also applicable to network-connected PDAs. The process of deploying MIDlet suites over a network is referred to as over-the-air provisioning, or OTA provisioning for short. OTA provisioning is not part of the MIDP specification, but it is likely to be the dominant mechanism for distributing MIDlets, and it will doubtless be included in the formal specification in the near future. An AMS that supports installation of MIDlets from an HTTP server is included in the Wireless Toolkit.

Over-the-Air Provisioning

With OTA provisioning, MIDlet providers install their MIDlet suites on web servers and provide hypertext links to them. A user activates the links to download the MIDlets to a cell phone via a WAP or Internet microbrowser. Figure 3-10 shows the steps involved in a typical MIDlet installation.

WARNING:  OTA provisioning as described in this section is not formally a part of the MIDP specification at the time of writing, but it is likely to be included in the next version of the specification. Meanwhile, it has the status of best-practice recommendation.

The process begins when the user fetches a page from the corporate web site of the (fictional) corporation ACME, Inc. The page includes a link to a suite of MIDlets that allow the user to browse ACME's product catalog and place orders directly from a Java-enabled cell phone. Intrigued by this prospect, the user activates the link, which causes a request for the target to be sent to ACME's web server. The link in question would look something like this:

Figure 3-10. Installing MIDlets using OTA provisioning

<A HREF="Suite.jad">Click here</A> to install the ACME MIDlet suite

As you can see, this link points to the JAD file for the ACME MIDlet suite. The request to retrieve this file is sent by the cell phone's browser (see step 2 in Figure 3-10), but it will be passed to and handled by the phone's application management software. To enable browsers to easily identify JAD files, the web server is configured to return them with the following MIME type:

text/vnd.sun.j2me.app-descriptor

In This Series The Mobile Information Device Profile and MIDlets, Part 4 In Part 4 of this five-part excerpt from J2ME in a Nutshell, author Kim Topley shows you how to develop MIDlets. The Mobile Information Device Profile and MIDlets, Part 3 Part three of a five-part book excerpt from O'Reilly's J2ME in a Nutshell by Kim Topley. This installment focuses on a MIDlet's three states: paused, active, and destroyed. The Mobile Information Device Profile and MIDlets, Part 2 This is the second of a five part book excerpt series based on O'Reilly's J2ME in a Nutshell by Kim Topley. Part 2 focuses on MIDlets and their suites. The Mobile Information Device Profile and MIDlets, Part 1 This is the first of a five part book excerpt series based on O'Reilly's J2ME in a Nutshell by Kim Topley. Part one is an overview of the Mobile Independent Device Profile and the MIDP Java platform.

On receipt of data with this content type, the phone's AMS activates and displays the content of the application descriptor, so that the user can decide whether or not to install the MIDlet suite. At this stage, the user has waited only a relatively short time for the download of the small JAD file. Since this file contains an attribute that corresponds to the size of the JAR file that contains the MIDlets as well as a textual description of the services they provide, the user should be able to choose whether to install them. This is the advantage of providing MIDlet information in both the JAD file and the JAR file manifest.

Should the user decide to install the MIDlets, the AMS looks for the MIDlet-Jar-URL attribute in the JAD file and sends a request to that URL for the JAR, which the server should return tagged with the MIME type application/java-archive.

At this point, the MIDlet suite is installed, and the user can select and run the individual MIDlets. Following installation, the AMS may be required to deliver a status report to the provisioning server indicating whether the suite was successfully installed and identifying the reason for failure if it was not. This report takes the form of a status code and a status message that is sent using an HTTP POST request to the URL given by the MIDlet-Install-Notify attribute in the JAD file. If this attribute is not present, no installation report is sent. Of course, the server must be configured to expect an installation report at the given URL. The server typically uses a servlet or CGI script to save the report along with details of the originator for later use.

TIP:   If you are not familiar with the HTTP protocol, you'll find a discussion of those parts of it that are supported by MIDP devices, including the POST request, in Chapter 6. More complete coverage of HTTP can be found in Java Network Programming by Elliotte Rusty Harold (O'Reilly & Associates, Inc.).

The status codes and their meanings are listed in Table 3-3.

Table 3-3: Status Codes Used to Report Success or Failure of MIDlet Installation

Status Code	Meaning
900	Success
901	Insufficient memory
902	Canceled by the user
903	Loss of network service (because of the network service loss, this report may never get delivered to the server)
904	JAR size mismatch
905	Attribute mismatch
906	Invalid descriptor

As well as implementing the MIDlet discovery and installation service as just described, the AMS software is required to provide the following functionality:

MIDlet suite updates

MIDlet updates are delivered just as the original MIDlet suite is: the user returns to the original server and requests the software as if an installation were being performed. Because the JAD file contains the version number of the associated MIDlet suite, the AMS can determine whether the software already installed is older than that on the server; if it is, the AMS can perform an upgrade, with permission from the user. Equally important, it can avoid downloading the JAR file if the newest version is already installed.

MIDlet selection and execution

The AMS provides the user with a means of selecting an installed MIDlet to run. The exact means by which this is achieved is device-dependent. On a cell phone, a menu item might give the user the ability to launch the AMS, or individual MIDlet suites may be included in the menu itself. On a PDA, MIDlet suites might be available in exactly the same way as native applications.

MIDlet removal

The Java application management software is responsible for removing MIDlet suites from the device on user request. MIDlets cannot be removed individually. Following successful removal, the application manager must also delete any persistent storage resources that were allocated to the MIDlet suite (see for further details). Because MIDlet removal causes loss of persistent data and is therefore almost certainly an irreversible process, the AMS will normally prompt the user for confirmation. The MIDlet suite vendor can use the MIDlet-Delete-Confirm attribute in the JAD file to include a message that should be displayed to the user before removal. This message can be used to warn the user of the consequences, if any, of removing the MIDlet suite.

The Wireless Toolkit Application Management Software

To prepare a MIDlet suite for remote installation, take the following steps:

1. Install the MIDlet suite JAR file on your web server.
2. Edit the JAD file so that its MIDlet-Jar-URL attribute points to the JAR file. Note that the specification requires that an absolute URL is required in the JAD file; relative URLs are not guaranteed to work. The Wireless Toolkit does not generate a JAD file containing an absolute URL, so you will need to edit it manually.
3. Place the JAD file on the web server.
4. Create an HTML or WML page with a hypertext link to the JAD file. The hypertext link must use an absolute URL, since application managers are not required to support relative URLs.
5. Configure the web server so that JAD files are returned with MIME type text/vnd.sun.j2me.app-descriptor and JAR files with MIME type application/java-archive.

The Wireless Toolkit contains a graphical AMS that can be used to test the OTA provisioning of MIDlet suites as well as to provide developers and vendors with a demonstration of typical application management and removal features. To use it, run the emulator provided with the Toolkit from the command line and pass it the argument -Xjam. Assuming you have installed the Wireless Toolkit in the directory c:\j2mewtk, issuing the following command in DOS starts the emulator and activates the AMS:

c:\j2mewtk\bin\emulator.exe -Xjam

When started, the application manager displays the Java logo and a copyright message. Press the Done button to show the application manager's main screen, which is shown on the left of Figure 3-11.

Figure 3-11. The Wireless Toolkit application management software

Pressing the Install button opens another screen that allows you to supply the URL of an HTML page that contains links to MIDlet suites, as shown on the right of Figure 3-11. This should be the URL of the HTML page set up previously, in step 4. The directory ora\ch3 in this book's example source code contains a sample HTML file called MIDlet.html that you can use for testing purposes. You should compile and package the MIDlet in this directory in the usual way and copy the files MIDlet.html, Chapter3.jad and Chapter3.jar onto your web server. Open Chapter3.jad and change the MIDlet-Jar-URL attribute to the absolute URL that corresponds to the location of the JAR file. Also edit the MIDlet.html file so that the HREF attribute in the <A> tag is the absolute URL of the JAD file.

Press the Go button to start the process. At this point, the AMS loads the HTML page and scans it for links that point to JAD files. A commercial application manager distinguishes these links from other links by making a request to the server for the target of the link and looking for a returned MIME type of text/vnd.sun.j2me.app-descriptor. However, the Wireless Toolkit AMS appears to take a shortcut and simply looks for links for which the target URL ends with .jad. If the target page does not contain any links that correspond to MIDlet suites, the error message shown on the left of Figure 3-12 appears.

Figure 3-12. Selecting a MIDlet suite for installation

Pages: 1, 2

Next Page