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-Vendor attributes and the optional
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:
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:
The Mobile Information Device Profile and MIDlets, Part 5
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 1
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
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.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:
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.
MIDlet-Iconattribute 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
nis an integer. The value of this attribute has the following form:
nameis the name of the MIDlet within the MIDlet suite.
iconis 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.
classis the name of the MIDlet's main class. The icon is optional; if no icon is required, it should be omitted:
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
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-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.