Editor's note: This is the final excerpt in a series from J2ME in a Nutshell, focusing on the 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. 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:
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:
In This Series
The Mobile Information Device Profile and MIDlets, Part 4
The Mobile Information Device Profile and MIDlets, Part 3
The Mobile Information Device Profile and MIDlets, Part 2
The Mobile Information Device Profile and MIDlets, Part 1
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
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.
|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|
As well as implementing the MIDlet discovery and installation service as just described, the AMS software is required to provide the following functionality:
MIDlet-Delete-Confirmattribute 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.
To prepare a MIDlet suite for remote installation, take the following steps:
MIDlet-Jar-URLattribute 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.
text/vnd.sun.j2me.app-descriptorand JAR files with MIME type
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:
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:
<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>
MIDlet-Jar-URLattribute in the JAD file must be an absolute URL pointing to the JAR file.
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
Ranking and others that are not visible in the screen shot, has been installed.
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.
Return to ONJava.com.
Copyright © 2009 O'Reilly Media, Inc.