The Mobile Information Device Profile and MIDlets, Part 5

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

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:

<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

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.

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.

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.

If you experience problems with this example, check that the server is properly configured and that the JAR and JAD files are consistent:

• The URL that you supply to the AMS must point to an HTML file that contains absolute hypertext links to one or more JAD files. The HTML file for this example looks like this:

<HTML>
    <HEAD>
        <TITLE>
        J2ME in a Nutshell Example MIDlet Download Page
        </TITLE>
    </HEAD>
    <BODY>
        Install the example MIDlet suite for
        <A HREF="http://localhost:8080/Chapter3.jad">Chapter 3</A> 
		of "J2ME in a Nutshell".
    </BODY>
</HTML>

• The web server must be configured to return JAD files with MIME type text/vnd.sun.j2me.app-descriptor.
• The MIDlet-Jar-URL attribute in the JAD file must be an absolute URL pointing to the JAR file.
• The JAD file must contain the mandatory attributes listed in Table 3-2.

If the AMS locates any JAD files, it displays a list of the links that point to them, using the text within the <A></A> tag pair to identify each MIDlet suite, as shown on the right side of Figure 3-12. This implementation does not display the MIDlet suite name or the JAR file size from the JAD file because it hasn't fetched it yet. To continue with the installation process, press the Install button.

At this point, the Wireless Toolkit AMS reads the JAD file from the server and uses the MIDlet-Jar-URL attribute to locate and fetch the JAR file. If this process succeeds, a confirmation message appears as shown on the left side of Figure 3-13. After a short pause, the application manager switches back to its main screen, shown in the center of Figure 3-13. If you compare this to Figure 3-11, you'll see that the main screen now contains the name of the MIDlet suite that was just installed. The list of installed MIDlets is saved on the device, so this list will reappear when you next run the emulator. In the case of a MIDlet suite containing more than one MIDlet, the list in the main screen displays each suite together with the MIDlets that it contains. An example of this is shown on the right-hand side of Figure 3-13, in which a MIDlet suite called Chapter5 containing individual MIDlets called Socket, Time, Ranking and others that are not visible in the screen shot, has been installed.

Figure 3-13. Installing a MIDlet suite

The main screen also includes an option that lets you launch MIDlets. If you select a MIDlet suite and choose this option, the usual MIDlet selector lets you pick the actual MIDlet to be run (see Figure 3-8). For a suite with multiple MIDlets, you can also choose an individual MIDlet from the main screen and launch it directly.

The Menu option provides access to the other application management features of the Wireless Toolkit AMS, presented in the form of a list, as shown in Figure 3-14.

Of these menu items, only the first three are worth discussing here. Each of these items operates on a MIDlet suite, so selecting any of them brings up another copy of the MIDlet selection screen so that you can choose the suite to which the command should apply.

The Info command displays the content of the JAD file that was fetched when the MIDlet suite was installed. Ideally, this information would be displayed to the user before the installation process starts, but, as noted previously, the Wireless Toolkit AMS does not implement this feature. Figure 3-15 shows the information displayed for the Chapter3 MIDlet suite.

The Update command reinstalls the MIDlet suite from its original source. As noted earlier, the AMS can compare the MIDlet version in its installed JAD file and the one it acquires from the server to determine if it already has the latest version of a MIDlet suite.

The Remove option deletes a MIDlet suite and all its associated persistent storage from the device. The Wireless Toolkit AMS displays a warning message and asks the user for confirmation before performing this operation (see Figure 3-16).

The Wireless Toolkit AMS can be controlled from the command line as well as through its user interface. For example, you can install a MIDlet suite directly from a web server using the command:

c:\j2mewtk\bin\emulator.exe -Xjam:install=http://www.yourserver.com/
    SOMETHING/Chapter3.jad

A complete description of the command-line arguments recognized by the Wireless Toolkit emulator can be found in Chapter 8.

1. The term Java Application Manager (or JAM) was originally used to describe the MIDP application management software. However, this resulted in confusion with the Java Application Manager software that is part of the CLDC reference implementation, which performs similar functions but with which it is incompatible.

Kim Topley has more than 25 years experience as a software developer and was one of the first people in the world to obtain the Sun Certified Java Developer qualification.

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

Return to ONJava.com.

Copyright © 2007 O'Reilly Media, Inc.