Packaging a MIDlet

Packaging a MIDlet into a MIDlet suite prepares it to be downloaded and run. A MIDlet suite consists of two files: a JAR file, which holds the MIDlet classes and other resources (such as graphics), and a Java™ application description (JAD) file, which holds attributes and values that describe the MIDlet suite and its MIDlets.

In addition to creating the JAR and JAD file, you can optionally sign the JAR file. This gives the MIDlet a better chance of being trusted. (See Chapter 1, “Introduction for more information on trusted MIDlets.)

This chapter shows you how to package one or more MIDlets into a MIDlet suite. It has the sections:

Creating a JAR File

A JAR file is a bundle of files that includes the MIDlet’s preverified files and other supporting files, such as graphics. You create the JAR file with the jar command. (The jar command is part of the Java 2 Platform, Standard Edition (J2SE™ platform) distribution. See the Release Notes for J2SE platform version requirements, and your Java platform documentation for more information on the jar command and JAR files.)

Ensure that all the preverified class files for the MIDlet suite are in their expected directory.

For example:

c:\midp2.0fcs> dir classes 
Volume in drive C has no label. 
... 
10/21/2002  03:32p                1,555 HelloMIDlet.class 
...

Copy any resource files for the MIDlets into the directory that contains the preverified class files.

The example MIDlet has no resource files. If, for example, it required a graphics file, mySplashImage.png, a command like the following one would put it in the same directory as the preverified files:

c:\midp2.0fcs> cp src/example/mySplashImage.png classes/

Decide what you will call the JAR file.

The rest of this chapter will refer it as jarFileName.

For example, the jarFileName for the MIDlet example will be HelloMIDlet.

Change directories to the location of the preverified class files and resource files.

For example,

c:\midp2.0fcs> cd classes

Create a manifest file.

The manifest file, filename.mf, is a text file that you can create with any text editor. It must contain at least the following attributes:

MIDlet-Name — Name that will be presented to the user

MIDlet-Version — Version number of the MIDlet in the major.minor.micro format described in the Java Product Versioning Specification at http://java.sun.com/products/jdk/1.2/docs/guide/versioning/spec/VersioningSpecification.html

MIDlet-Vendor — Creator of the MIDlet.

If you have used any security-sensitive APIs, you can also declare them in the manifest file. (If they are not in this file, they must be in the JAD file.) To declare them, use the following attributes:

MIDlet-Permissions – Permissions that are critical to the correct functioning of the MIDlet suite

MIDlet-Permissions-Opt – Permissions that the MIDlet suite would like, but that it can function correctly without (For example, use this if the MIDlet suite could run with reduced functionality if the permission were not available.)

The values for MIDlet-Permissions and MIDlet-Permissions-Opt are comma-separated lists. Leading and trailing white space (Unicode U+0020) and tabs (Unicode U+0009) are ignored. The following table shows the correspondence of MIDP 2.0 functionality and permissions:

TABLE 4 – APIs and Their Corresponding Permission
API	Corresponding Permission Name
javax.microedition.io.HttpConnection	javax.microedition.io.Connector.http
javax.microedition.io.HttpsConnection	javax.microedition.io.Connector.https
javax.microedition.io.Connector	Use the permission corresponding to the protocol you used when you created a connection: `javax.microedition.io.Connector.http` `javax.microedition.io.Connector.https` `javax.microedition.io.Connector.datagram` `javax.microedition.io. Connector.datagramreceiver` `javax.microedition.io.Connector.socket` `javax.microedition.io.Connector.serversocket` `javax.microedition.io.Connector.ssl` `javax.microedition.io.Connector.comm`
javax.microedition.io.PushRegistry	javax.microedition.io.PushRegistry

The manifest file can also contain the following attributes. (If they are not in this file, they must be in the JAD file.)

MIDlet-n — Comma-separated list of the nth MIDlet’s name, icon, and class where n is the nth MIDlet in the JAR file. The lowest value of n is one, and n increments by one for each consecutive MIDlet. Supplying an icon is optional.

MicroEdition-Profile — J2ME platform profiles that the MIDlet requires. Multiple profiles are separated with a blank (Unicode x20). For MIDP 2.0, the value should be MIDP-2.0.

MicroEdition-Configuration — J2ME platform configuration that the MIDlet requires. Multiple configurations are separated with a blank (Unicode x20). For MIDP 2.0, the value should be CLDC-1.0.

The manifest file is also permitted to contain other attributes. For more information on the legal attributes in a MIDlet’s a JAR file, see the specification for the Mobile Information Device Profile 2.0 [JSR-000118] at
http://jcp.org/jsr/detail/118.jsp.

For example, the manifest file for the HelloMIDlet.jar file, called HelloMIDlet.mf, looks like this:

MIDlet-Name: HelloWorld 
MIDlet-Version: 2.0 
MIDlet-Vendor: Sun Microsystems, Inc.

(If you are following this example by creating the Hello MIDlet, you should know that the HelloMIDlet.mf file is shipped in the midpInstallDir\src\example directory. Instead of entering a new version of the file, you can copy it into the midpInstallDir\classes directory.)

Create the JAR file with the jar tool.

Put the manifest file, class files, and resource files into the JAR file. (See your Java platform documentation for more information on the jar command.) For example:

c:\midp2.0fcs\classes> jar -cmf HelloMIDlet.mf HelloMIDlet.jar HelloMIDlet.class

Creating a JAD File

A JAD file is a text file that you create with any text editor. Its lines have the following syntax:

The JAD file may also contain the other attributes, including those listed in Step 5 in the previous section. For more information on the legal attributes in a MIDlet’s a JAD file, see the specification for the Mobile Information Device Profile 2.0 [JSR-000118] at http://jcp.org/jsr/detail/118.jsp.

The JAD and JAR file must have the same values for the MIDlet-Name, MIDlet-Version, and MIDlet-Vendor attributes. If the values differ, MIDP will not be able to load the MIDlet.

If the JAD and JAR file have other attributes in common, the requirements depend on whether the MIDlet suite is trusted:

For example, the JAD file for the Hello MIDlet, HelloMIDlet.jad, could look like this:

Signing a JAR File

Establishing trust is important for MIDlet suites that use security-sensitive APIs because trusted MIDlets can typically access more protected functionality than untrusted ones. Checking the signature of a MIDlet suite is one way that a device can determine whether to trust a MIDlet suite. As a result, signing a MIDlet suite makes it more likely that your MIDlet suite will be trusted by a device. (See Using MIDP for more information on signatures and certificates.)

The HelloMIDlet does not access protected APIs, so it is not necessary to sign its MIDlet suite. This section signs the MIDlet suite just to show how it is done.

The example below signs the MIDlet suite the RSA key pair provided with this release. The key pair is in the file midpInstallDir\bin\j2se_test_keystore.bin, which is a keystore that can be managed with the J2SE platform’s keytool utility. (See http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html for more information on the keytool utility.) The password for the file is keystorepwd. The alias of the key pair is dummyca and its private-key password is keypwd. The file is provided for testing purposes.

For MIDlets that you will publish, you will probably use an RSA key pair backed by a certificate or certificate chain from a certificate authority. The certificate authority vouches for your public/private key pair. You must have imported that certificate or certificate chain into a J2SE keystore with the J2SE platform’s keytool utility.

Add the certificate for your public key pair to the JAD file using the JadTool utility.

The JadTool utility will add the certificate as the value of an attribute named MIDlet-Certificate-m-n where m is the number of the certificate chain (it defaults to one; you can provide a different number with the -chainnum switch), and n is an integer that, for new certificates, begins at one and increments by one each time you add a new certificate to the JAD file.

For example, the following command would add the certificate as the value of the attribute MIDlet-Certificate-1-1 to the JAD file:

c:\midp2.0fcs\classes> java -jar ../bin/JadTool.jar -addcert -keystore ../bin/j2se_test_keystore.bin -alias dummyca -storepass keystorepwd -inputjad HelloMIDlet.jad -outputjad HelloMIDlet.jad

Optionally, verify that the certificate was added to the JAD file by using the JadTool utility to list the certificate in the JAD file.

c:\midp2.0fcs\classes> java -jar ../bin/JadTool.jar -showcert -certnum 1 -inputjad HelloMIDlet.jad 
Subject: C=US, ST=CA, L=Santa Clara, O=dummy CA, OU=JCT, CN=thehost 
Issuer : C=US, ST=CA, L=Santa Clara, O=dummy CA, OU=JCT, CN=thehost 
Serial number: 3d3ece8a 
Valid from Wed Jul 24 08:58:02 PDT 2002 to Sat Jul 21 08:58:02 PDT 2012 
Certificate fingerprints: 
  MD5: 87:7f:5e:64:c8:dd:b4:bf:35:39:76:87:99:9b:68:82 
  SHA: 9d:c0:88:ce:08:83:cd:e6:fe:13:8b:26:f6:b4:df:e2:da:3c:25:98

If you have a key pair backed by a certificate chain, import the intermediate certificates.

Import the intermediate certificates using the JadTool utility with the -addcert switch shown in Step 1, taking care to use the correct chain order. That is, if the Acme company provides a certificate that vouches for your key pair, and the WidgetCertificates company vouches for the Acme certificate, and, finally, Verisign vouches for the WidgetCertificates certificate, you would import the Acme certificate followed by the WidgetCertificate. The Acme certificate would MIDlet-Certificate-1-2 and the WidgetCertificate certificate would be
MIDlet-Certificate-1-3.

Note that you do not import the certificate of the root CA (that is, the certificate at the end of the chain, which is the certificate from Verisign in this example). The CA’s public key will be on the device.

Sign the JAR file using the JadTool utility.

The JadTool utility will sign the JAR file, base64 encode the signature, and store it as the value of the MIDlet-Jar-RSA-SHA1 attribute of the output JAD file.

Note – Be sure that the key you use to sign the JAR file is from the same JCA keystore entry as key pair you specified in Step 1. The JadTool utility does not check that you are signing the JAR file with a keystore entry that has a certificate in the JAD file.

For example:

c:\midp2.0fcs\classes> java -jar ../bin/JadTool.jar -addjarsig -keystore ../bin/j2se_test_keystore.bin -alias dummyca -storepass keystorepwd -keypass keypwd -jarfile HelloMIDlet.jar -inputjad HelloMIDlet.jad -outputjad HelloMIDlet.jad

Chapter 4