Packaging MIDlets - Wireless Java Developing with J2ME, Second Edition

Packaging MIDlets

MIDlets are deployed in MIDlet suites. A MIDlet suite is a collection of MIDlets with some extra information; it is composed of two files. One is an application descriptor, which is a simple text file. The other is a JAR file that contains the class files and resource files that make up your MIDlet suite. Like any JAR file, a MIDlet suite's JAR file has a manifest file. Figure 3-2 shows a diagram of a MIDlet suite.

Figure 3-2: Anatomy of a MIDlet suite

If you're using a tool like the J2ME Wireless Toolkit, you don't need to worry much about MIDlet suite packaging because most of the details are handled automatically. If you want to understand things at a lower level, or if you're just curious, keep reading for a complete description of MIDlet suite packaging.

Packaging a MIDlet suite consists of three steps:

The class files and resource files that make up the MIDlets are packaged into a JAR file. Usually, you'll use the jar command line tool to accomplish this.
Additional information that's needed at runtime is placed in the JAR's manifest file. All JARs include a manifest; a MIDlet suite JAR contains some extra information needed by application management software.
An application descriptor file must also be generated. This is a file with a .jad extension that describes the MIDlet suite JAR. It can be used by the application management software to decide whether a MIDlet suite JAR should be downloaded to the device.

MIDlet Manifest Information

The information stored in a MIDlet's manifest file consists of name and value pairs, like a properties file. For example, an unadorned JAR manifest might look like this:

Manifest-Version: 1.0
Created-By: 1.3.0 (Sun Microsystems Inc.)

A MIDlet JAR manifest for Jargoneer looks like this:

Manifest-Version: 1.0
MIDlet-1: Jargoneer, Jargoneer.png, Jargoneer
MIDlet-Name: Jargoneer
MIDlet-Version: 1.0
MIDlet-Vendor: Sun Microsystems
Created-By: 1.3.0 (Sun Microsystems Inc.)
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-1.0

The extra attributes describe software versions, class names, and other information about the MIDlet suite. The following attributes must be included:

MIDlet-Name: Despite the moniker, this attribute actually refers to the name of the entire MIDlet suite, not just one MIDlet.
MIDlet-Version: This describes the version of the MIDlet suite. It's a number you pick yourself in the form major.minor.micro.
MIDlet-Vendor: This is your name or the name of your company.

MIDlet-n: For each MIDlet in the MIDlet suite, the displayable name, icon file, and class name are listed. The MIDlets should be numbered starting from 1 and counting up. For example, several MIDlets in a single MIDlet suite could be listed like this:

MIDlet-1: Sokoban, /icons/Sokoban.png, example.sokoban.Sokoban
MIDlet-2: Tickets, /icons/Auction.png, example.lcdui.TicketAuction
MIDlet-3: Colors, /icons/ColorChooser.png, example.chooser.Color
MIDlet-4: Stock, /icons/Stock.png, example.stock.StockMIDlet

MicroEdition-Configuration: This attribute describes the J2ME configurations upon which this MIDlet suite can run. Multiple configuration names should be separated by spaces.
MicroEdition-Profile: This describes the set of profiles upon which this MIDlet suite can run. For MIDP 1.0 applications, this is MIDP-1.0. For applications that can run on MIDP 1.0 or MIDP 2.0, use "MIDP-2.0 MIDP-1.0".

In addition to the required manifest attributes, the following attributes may also be defined:

MIDlet-Description: The description of the MIDlet suite goes in this attribute.
MIDlet-Icon: Icons for individual MIDlets are described in the MIDlet-n attributes. This attribute specifies an icon to represent the entire MIDlet suite.
MIDlet-Info-URL: If additional information about the MIDlet suite is available online, use this attribute to list the URL.
MIDlet-Data-Size: If you know how many bytes of persistent data are required by the MIDlet suite, you can specify the number with this attribute.

Tip?/td>

Don't get tripped up by the attribute names. Many of them appear to refer to a single MIDlet, like MIDlet-Name and MIDlet-Description. In fact, these attributes describe an entire MIDlet suite. The only attribute that applies to a specific MIDlet is the MIDlet-n attribute, which is used to list each MIDlet in the suite.

In MIDP 2.0, several additional attributes may be included. MIDP 2.0 protects network APIs from unauthorized access using a permission scheme, which will be fully discussed later in this chapter. MIDlets can list necessary permissions and optional permissions in the MIDlet JAR manifest as follows:

MIDlet-Permissions: Use this attribute to list permissions that are critical to the operation of the MIDlet suite. Multiple permissions are separated by commas.
MIDlet-Permissions-Opt: This attribute lists permissions that may be used but are not critical for this MIDlet suite.

Finally, MIDP 2.0 also provides a way for MIDlet suites to signal their dependence on optional APIs:

MIDlet-Extensions: List the optional APIs used by this MIDlet suite in this attribute. The exact names are determined by the individual optional API specifications.

Application Descriptor

The attributes in a MIDlet suite JAR are used by the application management software to run MIDlets within a suite. The application descriptor, by contrast, contains information that helps a device decide whether or not to load a MIDlet suite. Because an application descriptor is a file separate from the MIDlet suite JAR, it is easy for a device to load and examine the file before downloading the MIDlet suite.

As it happens, a lot of the information in the application descriptor is the same as the information that's in the MIDlet suite JAR. For example, the application descriptor must contain the MIDlet-Name, MIDlet-Version, and MIDlet-Vendor attributes. In addition, it should include the following:

MIDlet-Jar-URL: This is the URL where the MIDlet suite JAR can be found.
MIDlet-Jar-Size: This is the size, in bytes, of the MIDlet suite JAR.

The application descriptor can optionally contain the MIDlet-Description, MIDlet-Icon, MIDlet-Info-URL, and MIDlet-Data-Size attributes.

Devices and emulators vary widely in their handling of MIDlet suite descriptors. Some will fail installation if any fields in the descriptor are incorrect while others are more lenient. A tool like the J2ME Wireless Toolkit is extremely useful in creating well-formed descriptors.

The application descriptor is useful in over the air (OTA) deployment. A device can download and inspect the descriptor, a relatively short file, before deciding whether or not the entire MIDlet suite JAR should be downloaded and installed. For OTA provisioning, the server's returned MIME type for the application descriptor should be text/vnd.sun.j2me.app-descriptor. This and more (a whole protocol) is described in the Over the Air User Initiated Provisioning Specification section of the MIDP 2.0 specification.

MIDlet Properties

There's one other possibility for attributes in the manifest or application descriptor. You can add attributes that have meaning to your MIDlets. MIDlets can retrieve the values of these attributes using the getAppProperty() in the javax.microedition.midlet.MIDlet class. An attribute can be listed in the application descriptor, JAR manifest, or both; if it is listed in both, the value from the application descriptor will be used. In general, it makes sense to store application properties in the application descriptor file. Because it's distinct from the MIDlet suite JAR, the application descriptor can easily be changed to modify the behavior of your MIDlets. You might, for example, store a URL or other configuration information in the application descriptor.

For example, suppose you put an application-specific attribute in the application descriptor, like this:

Jargoneer.url: http://www.dict.org/bin/Dict

Inside the MIDlet, you can retrieve the value of the attribute like this:

String url = getAppProperty("Jargoneer.url");

Changing the URL is as easy as changing the application descriptor, a simple text file. None of your code needs to be recompiled. This could be useful if you were expecting to distribute many copies of a MIDlet and wanted to share the server load among a group of servers. You could distribute the same MIDlet suite JAR with a group of different application descriptors, each one using a MIDlet attribute to point to a different server.

[ directory ]