ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

The Mobile Information Device Profile and MIDlets, Part 2
Pages: 1, 2, 3

The job of the manifest file is to indicate to the device the name and version of the MIDlet suite in the JAR and to specify which of the class files it contains correspond to the individual MIDlets. In order to make use of this information, however, the device must download the JAR and extract the manifest. Having done this, it can then display the values associated with the MIDlet-Name, MIDlet-Version, and MIDlet-Vendor attributes and the optional MIDlet-Description and MIDlet-Icon attributes. These attributes allow the user to decide whether the MIDlets should be installed. However, the JAR for a MIDlet suite might be quite large and may take some time to retrieve over the relatively slow networks to which mobile devices typically have access. If the only useful description of its content were in the JAR itself, a lot of time might be wasted transferring large files that are immediately rejected as uninteresting.



To solve this problem, some of the attributes from the manifest file, together with extra information, is duplicated in the JAD file. Instead of downloading the whole JAR, a MIDP device first fetches its JAD file, which is much smaller than the JAR and can be transferred quickly. The device then displays the JAD file's contents to the user so that she can decide whether to fetch the JAR file. The JAD contains some attributes that come from the manifest file and others that do not appear in the manifest. The common attributes are as follows:

  • MIDlet-Name
  • MIDlet-Vendor
  • MIDlet-Version
  • MIDlet-Description
  • MIDlet-Icon
  • MIDlet-Info-URL
  • MIDlet-Data-Size

These attributes (with the possible exception of the last one) can all be presented to the user as an aid to deciding whether the content of the corresponding JAR file is interesting enough to download. The first three of these attributes are mandatory in both JAR and JAD files, and the MIDP specification requires that their values be identical. The remaining attributes are all optional. If they appear in both the manifest and the JAD file, the value in the JAD file takes precedence over that in the manifest (and at this stage, the device can see only the value in the JAD file).

The JAD file also contains two other attributes that are not present in the manifest file:

Related Articles:

The Mobile Information Device Profile and MIDlets, Part 5
This is the final excerpt in a series on MIDP and MIDlets from J2ME in a Nutshell, focusing on the delivery and installation of MIDlets.

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 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.

  • MIDlet-Jar-Size
  • MIDlet-Jar-URL

The MIDlet-Jar-Size attribute can be displayed to the user to help determine how long it will take to fetch the JAR; it also enables the user to guess whether the device has enough free space to install the JAR. Assuming the user decides to install the MIDlet suite, the next step is to fetch the JAR itself, which can be found by using the value of the MIDlet-Jar-URL attribute.

Suppose a company called "Wireless Java Inc." creates a suite of MIDlets called WirelessTrader that allow a user to do online stock trading from a MIDP device. The suite contains two MIDlets, one for trading, the other for simply browsing through stock prices. The main classes for these two MIDlets are called com.wireless.TradeMIDlet and com.wireless.BrowseMIDlet, and they make use of common code in the com.wireless.Utils class. The manifest for this suite would look something like this:

MIDlet-Name: WirelessTrader
MIDlet-Vendor: Wireless Java Inc.
MIDlet-Version: 1.0.1
MIDlet-Description: A set of MIDlets for online trading.
MIDlet-Icon: /com/wireless/icons/wireless.png
MIDlet-Info-URL: http://www.wireless.com/trader/info.html
MIDlet-Data-Size: 512
MicroEdition-Profile: MIDP-1.0
MicroEdition-Configuration: CLDC
MIDlet-1: StockTrader,/com/wireless/icons/trader.png,com.wireless.TradeMIDlet 
MIDlet-2: StockBrowser,/com/wireless/icons/browser.png,com.wirelessBrowseMIDlet

In the JAR, this file would appear as META-INF/MANIFEST.mf. The JAR would also include the following files:

  • /com/wireless/BrowseMIDlet.class
  • /com/wireless/TradeMIDlet.class
  • /com/wireless/Utils.class
  • /com/wireless/icons/browser.png
  • /com/wireless/icons/trader.png
  • /com/wireless/icons/wireless.png

Note the following about the attributes in the manifest file and the content of the JAR:

  • The JAR contains the two MIDlet class files and the class file for com.wireless.Utils, which contains code that is used by both MIDlets. This latter file, however, does not need to be referenced from the manifest file. The JAR also contains the three icons that are referred to from the manifest file.

  • The MIDlet-Icon attribute contains the absolute path of the icon file for the MIDlet suite, relative to the JAR file itself.

  • Each MIDlet has an attribute that describes it; the attribute's name is of the form MIDlet-n, where n is an integer. The value of this attribute has the following form:

    name,icon,class
  • name is the name of the MIDlet within the MIDlet suite. icon is the full path of the icon that the device may use along with the MIDlet name when displaying the content of the MIDlet suite to the user. class is the name of the MIDlet's main class. The icon is optional; if no icon is required, it should be omitted:

    MIDlet-2: StockBrowser,,com.wireless.BrowseMIDlet 
  • Note that even if an icon is specified, the device is not obliged to display it. The same applies to the MIDlet suite icon defined by the optional MIDlet-Icon attribute.

The JAD file for this suite can be constructed like this:

MIDlet-Name: WirelessTrader
MIDlet-Vendor: Wireless Java Inc.
MIDlet-Version: 1.0.1
MIDlet-Description: A set of MIDlets for online trading.
MIDlet-Info-URL: http://www.wireless.com/trader/info.html
MIDlet-Data-Size: 512
MIDlet-Jar-Size: 10312
MIDlet-Jar-URL: http://www.wireless.com/trader/Midlets.jar

This file contains the information that the device displays to the user, together with the URL of the MIDlet suite JAR. In this case, the common attributes have the same values in the manifest and the JAR, but it is possible to override the MIDlet-Description, MIDlet-Icon, MIDlet-Info-URL, and MIDlet-Data-Size attributes by specifying different values in the JAD file.

In order to be fully portable, the JAD file should be encoded using ISO-8859-1, because all MIDP implementations are required to support this character encoding. The successful use of any other encoding depends on the target device, which may not support the encoding, and the way in which the JAD file is transported to the device. If, for example, the file is fetched using HTTP, the Content-Type header can be used to specify the encoding as described in the later section "Delivery and Installation of MIDlets." In some cases, it is useful to be able to include in the JAD file Unicode characters that are not available in the ISO-8859-1 encoding or that are not easy to access from a standard keyboard. The MIDP reference implementation allows you to use Unicode escape sequences of the form \uxxxx to overcome encoding limitations. For example, the following line includes the copyright character (Unicode value 00A9) in the MIDlet suite description:

MIDlet-Description: A set of MIDlets for online trading. \u00A9 Wireless Java Inc.

Although this feature is available in the MIDP reference implementation, it is not mentioned in the MIDP specification, so there is no guarantee that real devices will actually support it.

At runtime, a MIDlet can access files from its JAR using the getResourceAsStream( ) method of java.lang.Class. Any file in the JAR, apart from class files, can be accessed this way. This is typically how you would include images or text files that should be displayed in the user interface, an example of which will be shown in Chapter 4. A MIDlet can also define its own private attributes in the manifest file and the JAD and retrieve them at runtime, as you'll see in "Developing MIDlets" later in this chapter.

Next time, learn MIDlet Execution Environment and Lifecycle.

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.


View catalog information for J2ME in a Nutshell

Return to ONJava.com.