Packaging

 
Packaging
The next step after preverification is to package your application. MIDlet suite packaging involves
two entities:
18
• a Java archive file of the MIDlet files
• an optional application descriptor file
Although you can choose to optionally package J2SE applications for deployment, the MIDP
specification requires that you package MIDlet suites using the Java archive (JAR) utility. In fact,
the MIDP specification requires that all MIDlet suites be delivered to devices in a compressed
JAR file format. Normally, servers that support delivery of MIDlet suites to devices store MIDlet
suite files in compressed JAR format. Either the server or the entity that uploads the file to the
server creates the compressed JAR file.
A JAR archive of a MIDlet suite can contain several types of files, as the following list indicates:
• a manifest file that describes the contents of the JAR file
• Java class files that comprise the MIDlets in the archive's MIDlet suite
• application resource files used by the MIDlets in the MIDlet suite
The JAR manifest file contains attributes that describe the contents of the JAR file itself. Its
presence in the JAR file is optional.
Another optional description file, called an application descriptor file, contains information about
the MIDlet suite. This file is sometimes called a Java application descriptor (JAD) file. Each
MIDlet suite can optionally have an associated application descriptor file.
The application descriptor file is used for two purposes. The device application management
software (AMS) uses the information in this file primarily to verify that the MIDlets in the JAR
file are appropriate for the device before it downloads the full JAR file. The AMS also uses the
information to manage the MIDlet. The device's AMS is responsible for installing and uninstalling
MIDlet suites. It also provides MIDlets with the runtime environment required by the MIDP
specification. Finally, the AMS manages MIDlet execution, namely, the starting, stopping, and
destruction of all MIDlets.
Finally, the MIDlets themselves can extract from the JAD file configuration specific attributes that
represent MIDlet parameters. The application resource file is the primary mechanism for
deploying MIDP application configurations.
Creating the JAR Manifest File
If you choose to supply a manifest file with your MIDlet suite JAR, you need to create it before
you create the JAR archive itself. You can create this file with any text editor. Afterwards, create
the JAR file using the standard J2SE JAR utility. The JAR utility is included as part of the
Wireless Toolkit utilities.
The MIDP specification requires that certain fields be present in the manifest file. The required
fields are shown in Table 2.2.
A manifest file contains lines of attributes, one attribute per line. Each attribute consists of a key
and a value. The key is followed by a colon, which separates it from its associated value. The
MANIFEST.MF file for the HelloWorld program resides in the HelloWorld/bin/ directory.
It looks like this:
MIDlet-1: HelloWorld, HelloWorld.png, HelloWorld
MIDlet-Name: HelloWorld
MIDlet-Vendor: Vartan Piroumian
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.0
19
MicroEdition-Profile: MIDP-1.0
Notice the attribute name MIDlet-1: in the MANIFEST.MF file. The manifest file distinguishes
the different MIDlets by numbering them MIDlet-1 through MIDlet-n. The number 1 must
identify the first MIDlet.
There are three values to the MIDlet-1 attribute. The first is the name of the MIDlet suite that
contains this MIDlet. This value can be a human-readable name. The second value is the name of
the PNG image file that the AMS uses as the icon to represent this MIDlet. The last value is the
name of the MIDlet class file that defines the MIDlet's execution entry point.
Perhaps the most important attributes are the MicroEdition-Configuration and the
MicroEdition-Profile attributes. The AMS uses these values to determine if the MIDlet is
suitable for the target device.
The MIDP specification also allows optional fields in the manifest file. Table 2.3 shows the
optional manifest file fields.
Table 2.2. Required MANIFEST.MF File Attributes
Attribute Name Description
MIDlet-Name The name of the MIDlet suite
MIDlet-Version The MIDlet suite version number, in the form
<major>.<minor>.<micro>, defined by the JDK product
versioning specification scheme
MIDlet-Vendor The application developer (company or individual)
MIDlet-<n> One per MIDlet in the suite; contains a comma-separated list of
the MIDlet textual name, icon, and class name of the nth MIDlet in
the suite
MicroEdition-
Profile
The J2ME profile needed to execute the MIDlet
MicroEdition-
Configuration
The J2ME configuration needed to execute the MIDlet
Creating the MIDlet Suite JAR File
Now that you've created the manifest file, you're ready to create the application JAR file. Use the
following jar command:
$ jar cmf bin/MANIFEST.MF bin/HelloWorld.jar -C classes/ . -C res .
$
Table 2.3. Optional MANIFEST.MF File Attributes
Attribute Name Description
MIDlet-
Description
A description of the MIDlet suite
MIDlet-Icon The name of a PNG file contained by the JAR
MIDlet-Info-URL A URL that contains additional information about this MIDlet suite
MIDlet-Data-Size The minimum number of bytes of persistent data that the suite
requires
This command creates the JAR file for your HelloWorld MIDlet suite. Listing the contents of
the bin/ directory reveals the newly created HelloWorld.jar file:
20
$ ls -l bin
total 2
-rw-r--r-- 1 vartan None 1393 HelloWorld.jar
-rw-r--r-- 1 vartan None 193 MANIFEST.MF
$
Listing the contents of the JAR file you just created produces the following output:
$ jar tf bin/HelloWorld.jar
META-INF/
META-INF/MANIFEST.MF
classes/./
classes/./HelloWorld.class
HelloWorld.png
$
As you can see, the manifest file is included in the JAR file. The JAR file contains the
single .class file for our HelloWorld application. It also contains a .png portable network
graphics format file that is intended to be a suitable choice for use as the application's icon. The
MANIFEST.MF file, of course, was created by hand as described previously.
Creating the MIDlet Suite Application Descriptor File
The application management software on a device such as a mobile phone uses the JAD file to
obtain information needed to manage resources during MIDlet execution. The application
descriptor file is optional, but useful nonetheless. You can use any text editor to create it, but you
must give the file a .jad extension. To avoid confusion, I recommend giving it a name that
represents the whole MIDlet suite.
Table 2.4. Required Application Descriptor File Attributes
Attribute Name Description
MIDlet-Jar-URL The URL of the MIDlet suite JAR file
MIDlet-Jar-Size The size (in bytes) of the JAR file
MIDlet-Name The name of the MIDlet suite
MIDlet-Vendor The application developer (for example, a company or individual
name)
MIDlet-Version The MIDlet suite version number, in the form
<major>.<minor>.<micro>, defined by the JDK product
versioning specification scheme
MicroEdition-
Configuration
The J2ME configuration required to execute MIDlets in this suite
MicroEdition-
Profile
The J2ME profile required to execute MIDlets in this suite
Table 2.5. Optional Application Descriptor File Attributes
Attribute Name Description
MIDlet-Data-Size The minimum number of bytes of persistent data that the suite
requires
MIDlet-Delete-
Confirm
Indicates whether AMS should request user confirmation before
deleting a MIDlet
MIDlet-Description A description of the MIDlet suite
MIDlet-Icon The name of a PNG file contained by the JAR
21
MIDlet-Info-URL A URL that contains additional information about this MIDlet suite
MIDlet-Install-
Notify
Indicates whether the AMS should notify the user of a new MIDlet
installation
In addition to the optional fields listed in Table 2.5, the JAD file can contain MIDlet-specific
attribute fields defined and named by the application developer. You can name these attributes
anything you like; however, you should not use "MIDlet-" in the attribute name. This prefix is
reserved for standard attribute names defined by the MIDP specification.
The JAD file for the HelloWorld program also resides in the HelloWorld/bin/ directory,
and its contents looks like this:
MIDlet-1: HelloWorld, HelloWorld.png, HelloWorld
MIDlet-Jar-Size: 1393
MIDlet-Jar-URL: HelloWorld.jar
MIDlet-Name: HelloWorld
MIDlet-Vendor: Vartan Piroumian
MIDlet-Version: 1.0
In particular, notice the MIDlet-Jar-Size attribute field. When you are using command-line
tools, you must manually edit the JAD file to update the value of the MIDlet-Jar-Size
attribute each time you build the JAR file to accurately reflect the size of the JAR file. The
directory listing of the bin/ directory indicates that your JAR file is 1393 bytes in length.
Therefore, the JAD file must accurately reflect this size, which it does.
Notice that some of the fields appear in both the manifest and JAD files. The reason is that the
MIDP specification requires their presence in both files. Three attributes in particular—MIDlet-
Name, MIDlet-Version, and MIDlet-Vendor—are worth special attention. They must have
the same value if present in both the JAD and manifest files. The MIDP specification stipulates
that a JAR file must not be downloaded if these three values are not duplicated in these two files.