ColdFusion MX Professional Projects

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

Packaging a MIDlet suite consists of three steps:

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

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

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

The 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 configuration required to run the MIDlet suite. For MIDP 1.0 suites, this will always be CLDC-1.0.

• MicroEdition-Profile: This describes the profile required by this MIDlet suite. For MIDP 1.0 applications, this is 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.

Application Descriptor

The attributes in a MIDlet suite JAR are used by the application management soft- ware 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.

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.