Wireless Java

Creating MIDlets

Now that you’re familiar with MIDlet states and the application manager, let’s create another MIDlet. As you’ve probably guessed by now, this involves the following five steps:

1. Write the MIDlet.

2. Compile the MIDlet’s source code.

3. Preverify the MIDlet’s class file.

4. Package the application in a JAR file.

5. Create a JAD file.

Let’s review each of these steps. First, we’ll look at the command-line technique that was shown in Chapter 1. Then, we’ll introduce the KToolbar application, which comes with the J2ME Wireless Toolkit and which can make our lives much easier.

Write the MIDlet

The first step in the development life cycle is to write the MIDlet. Example 4-2 shows a simple MIDlet, PaymentMIDlet. This MIDlet creates a List object of type EXCLUSIVE (that is, only one option can be selected at a time), and adds three methods of payments to it. It displays a list of options for the user to select a method of payment.

Example 4-2. Sample MIDlet

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;

public class PaymentMIDlet extends MIDlet {

    // The display for this MIDlet
    private Display display;

    // List to display payment methods
    List method = null;

    public PaymentMIDlet(  ) {
       method = new List("Method of Payment", 
           Choice.EXCLUSIVE); 
    }

    public void startApp(  ) {
        display = Display.getDisplay(this);
        method.append("Visa", null);
        method.append("MasterCard", null);
        method.append("Amex", null);
        display.setCurrent(method);
    }

    /**
     * Pause is a no-op since there are no background
     * activities or record stores that need to be closed.
     */

    public void pauseApp(  ) {
    }

    /**
     * Destroy must cleanup everything not handled by the 
     * garbage collector. In this case there is nothing to
     * cleanup.
     */

    public void destroyApp(boolean unconditional) {
    }
}

Compile the Source Code

To compile the source code with the command-line tools of the Java Wireless Toolkit, use the javac command. Remember that you should use the -bootclasspath option to make sure the source code is compiled against the correct CLDC and MIDP classes.

C:\midlets> javac -bootclasspath C:\j2mewtk\lib\midpapi.zip PaymentMIDlet.java

This command produces the PaymentMidlet.class file in the current directory. This is a slightly simplified version of the command we used in Chapter 1, which puts the resulting class file in a temporary directory.

Preverify the Class File

The next step is to preverify the class file using the preverify command:

C:j2mewtk\bin> preverify -classpath C:\midlets;C:\j2mewtk\lib\midpapi.zip
    PaymentMIDlet

Again, a slightly different approach. This command creates an output subdirectory in the current directory and writes a new file PaymentMIDlet.class. This is the preverified class that the KVM can run with its modified class verifier.

Package the Application in a JAR File

In order to enable dynamic downloading of MIDP applications, the application must be packaged in a JAR file. To create a JAR file, use the jar command:

C:\midlets> jar cvf payment.jar PaymentMidlet.class

Create a JAD File

A JAD file is necessary if you want to run a CLDC-compliant application. Example 4-3 shows a sample JAD file for the payment MIDlet.

Example 4-3. A sample JAD file

MIDlet-1: payment,,PaymentMIDlet
MIDlet-Name: Payment
MIDlet-Version: 1.0
MIDlet-Vendor: ORA
MIDlet-Jar-URL: payment.jar
MIDlet-Jar-Size: 961

Once you have the JAD file, you can test your application using the MIDP emulator using the emulator command of the Java Wireless Toolkit, as shown here:

C:\j2mewtk\bin> emulator -Xdescriptor:C;\midlets\payment.jad

If all goes well, activate the MIDlet and you will see output similar to Figure 4-2.

Figure 4-2. Running the payment MIDlet

If your MIDP application consists of multiple MIDlets, they can all be in one JAR file as a MIDlet suite. However, you would need to specify them in the JAD file using the MIDlet-n entry, where n is the number of the MIDlet. Consider the JAD file in Example 4-4, with three hypothetical MIDlets.

Example 4-4. Three hypothetical MIDlets

MIDlet-1: Buy, , BuyMidlet
MIDlet-2: Sell, , SellMidlet
MIDlet-3: Trade, , TradeMidlet
MIDlet-Name: Trading
MIDlet-Version: 1.0
MIDlet-Vendor: ORA
MIDlet-Jar-URL: trade.jar
MIDlet-Jar-Size: 2961

If you run this JAD file, you would see something similar to Figure 4-3.

Figure 4-3. MIDlet suite

A MIDP application may consist of multiple MIDlets, as shown in Figure 4-3. Similarly, a desktop application consists of menus and options, as shown in Figure 4-4.

Figure 4-4. Desktop application

Simplifying the Development

You have now seen how to compile, preverify, create JAR and JAD files, and run MIDlets from the command line. This is fine if you want to understand what’s happening behind the scenes. However, there is an alternative. An integrated development environment, such as the J2ME Wireless Toolkit, can be used to simplify the development and deployment of MIDlets. The J2ME Wireless Toolkit comes with an application called KToolbar. The following steps show how to use the KToolbar to set up a simple MIDlet, develop the application, package it, and run it.

1. In Microsoft Windows, choose Start → Programs → J2ME Wireless Toolkit → KToolbar to start the development environment. Figure 4-5 shows the resulting KToolbar screen.

   

   Figure 4-5. KToolbar screen

2. Click on the New Project button to create a new project called payment, and call the MIDlet class PaymentMIDlet, as shown in Figure 4-6.

   

   Figure 4-6. New project

3. Once you click on Create Project in Figure 4-6, you will get a setting project window, as shown in Figure 4-7. This window allows you to modify the MIDlet attributes. All the required attributes are shown in Figure 4-7.

   

   Figure 4-7. Required attributes

4. If you click on the Optional tab, you will get a window with all the optional attributes, which are shown in Figure 4-8.

   

   Figure 4-8. Optional attributes

5. Once you click OK, you will get the original KToolbar screen with information to indicate where to save your source and resource files. Assuming the Wireless Toolkit is installed in the directory C:\J2MEWTK, then you will be told to save your Java source files in C:\J2MEWTK\apps\payment\src and your resource files (e.g., icons) in C:\J2MEWTK\apps\payment\res.

Now, use your favorite text editor and write PaymentMIDlet, or simply copy the source from Example 4-2. Then, save it in the required location and click on the Build button to compile it. Note that the KToolbar application performs all the steps of compiling the application, preverifying the classes, compressing them into a JAR file, and creating a corresponding JAD file for you. All you have to do is to click the Run button to run it. Then you can test your MIDlet using a default phone, Motorola’s i85s, or a Palm OS, as shown in Figure 4-9.

Figure 4-9. Select a testing device (upper right corner of KToolbar)

Choose your favorite testing device to test the MIDlet. For example, Figure 4-10 shows the PaymentMIDlet running in a default gray phone device.

Figure 4-10. PaymentMIDlet on the default phone

Figure 4-11 shows the PaymentMIDlet running on Motorola’s i85s device.

Figure 4-11. PaymentMIDlet on the Motorola i85s

Figure 4-12 shows the same application running on a Palm Pilot and Figure 4-13 shows the PaymentMIDlet application running on RIM’s BlackBerry. Chapter 9 discusses how to install the Java Application Manager on a real Palm OS device and how to convert existing MIDlets into PRC executable files for handheld devices running Palm OS 3.5 or higher.

Figure 4-12. PaymentMIDlet on Palm OS

Figure 4-13. PaymentMIDlet running on RIM’s BlackBerry

Deploying MIDlets

As of this writing, deploying MIDlets is still an experimental process. However, the Java application manager that comes with the MIDP reference implementation now provides some clues about how we can deploy MIDlets to various devices. Specifically, MIDlets can be installed in two ways:

• Using a data cable or other dedicated physical connection from a local host computer

• Using a network to which the device is intermittently connected

The first method works well with PDAs, which are often used with a host computer, with which the PDAs frequently synchronize their data. For example, the MIDP for Palm implementation, which is discussed in Chapter 9, is a good example of this; its application manager allows MIDlet suites to be installed from a host PC during the synchronization process.

The second method is more popular when installing MIDlets on cell phones and other wireless devices. With these devices, the most likely delivery transport is the wireless network itself. The process of deploying MIDlet suites over a network is referred to as over-the-air (OTA) provisioning. OTA provisioning is not yet part of the MIDP specification, but it is likely to become the dominant mechanism for distributing MIDlets and will probably be included in the formal specification soon.

Deploying OTA

As of this writing, OTA provisioning is just starting to be used with J2ME devices such as the Motorola i85s/i50x series of cell phones. OTA provisioning allows MIDlet providers to install their MIDlet suites via web servers that provide hypertext links. This allows you to download MIDlet suites to a cell phone via a WAP or Internet microbrowser. Here is a brief description of how this process works.

First, to deploy a MIDlet from a web server, you need to reconfigure your web server by adding a new MIME type:

text/vnd.sun.j2me.app-descriptor jad

How to add the MIME type depends on what server you are running. For example, if you’re running Apache Tomcat, you would add a new MIME type by adding a new entry in the web.xml server configuration file, as follows:

<mime-mapping>
   <extension>jad</extension>
   <mime-type>text/vnd.sun.j2me.app-descriptor</mime-type>
</mime-mapping>

You would then use the following type of procedure to install a MIDlet suite from a web page:

1. Click on a link, which will probably request a file with a JAD extension, such as the following:

   <A HREF='MyApp.jad'>Click here to install the MIDlet suite</A>

2. The server will then send the MyApp.jad file to the phone with the MIME type set to text/vnd.sun.j2me.app-descriptor, as described earlier. Recall that the JAD file must contain the MIDlet-Jar-URL and MIDlet-Jar-Size properties, which tell the device where to download the MIDlet suite, as well as the suite’s size in bytes.

3. The Java application manager on the phone will then ask if you want to install the MIDlet into the phone, assuming that the phone has the resources to run the MIDlet (i.e., that there’s enough space on the device to hold the MIDlet suite).

4. If you answer yes, the entire JAR file will be downloaded from the server, using the properties specified in the JAD file.

Once the MIDlet is downloaded, it will be installed the first time you try to use it. A downloaded MIDlet stays on the device until you remove it (unlike Java applets).

Deploying to the Motorola i50x/i85s

You can also download J2ME applications to a Motorola/Nextel i50x or i85s device from your desktop through a data cable. This cable does not come with the phone itself, but can be ordered online from Nextel. The iDEN update software can then be downloaded from the iDEN development site (http://www.motorola.com/idendev).

In addition, you can also purchase a data cable that comes with a CD-ROM containing the iDEN update software from Nextel from this site. Obtaining the software may involve authorization from your carrier, which can take between one and five days. Once you are granted authorization, however, you can install applications on up to five individual phones. The following paragraphs describe how to use the Motorola iDEN update software to download a J2ME MIDlet to your phone.

After you have obtained the update software, start it up and choose the J2ME Developers tab on the far left. This will result in a screen similar to that in Figure 4-14. From here, you can choose a JAD file to download the application into your phone through the data cable. Note that the JAD file and the JAR file must reside in the same directory and must have the same filename (excluding the extension).

Figure 4-14. Motorola iDEN update software

For the most part, downloading an application to the phone is easy. However, the Motorola i85s and i50x phones will perform a number of checks to ensure the integrity of the application while installing it. You should observe the following rules to ensure that the phone will install the application.

The JAD file downloaded to the i85s or i50x must contain at least the following entries, which are case-sensitive:

MIDlet-Name:
MIDlet-Version:
MIDlet-Vendor:
MIDlet-Jar-Size:
MIDlet-Jar-URL:

It can also contain the following optional entries:

MIDlet-Description:
MIDlet-Info-URL:
MIDlet-Data-Size:

In addition, the JAD file can contain any other MIDlet-specific information that does not begin with the letters “MIDlet-”.

Remember from Chapter 3 that the JAR file must contain a manifest with at least the following information, which must be identical to the data in the JAD file:

MIDlet-Name:
MIDlet-Version:
MIDlet-Vendor:

If you do not include this information in the manifest, the phone will respond with a “Descriptor Error” when it is attempting to install the application. If this happens, simply press the Menu button while the MIDlet is selected and remove it from the system.

Here are some other things to note when downloading to the Motorola i85s or i50x:

• The JAD file is case-sensitive.

• The maximum file length for both the JAD and the JAR file is 16 characters, which includes the four characters for the extension (e.g., .JAD or .JAR).

• The byte size of the JAR file must be accurately stated in the JAD file.

• Each of the attributes in the JAD and JAR file manifests must have a value associated with it. You cannot leave an attribute value blank.

• Classes which are instantiated using the Class.forName( ) method must be identified in the JAD file using the attribute: iDEN-Install-Class-n:, where n is a positive integer. The class name is listed afterward without the .class extension.

Example 4-5 shows the manifest information that we would be using if we wanted to download the HelloMidlet application from Chapter 1 to the Motorola i85s. Remember that the manifest must contain the three specified attributes (MIDlet-Name, MIDlet-Version, and MIDlet-Vendor) and that they must be identical to the values in the JAD file. If they differ, the phone will not install the MIDlet. We have also included the MIDlet class identification information and the profile and configuration version numbers, which we recommend that you include in your MIDlet manifests as well.

Example 4-5. Manifest.mf

MIDlet-Name: HelloMidlet
MIDlet-Vendor: ORA
MIDlet-Version: 1.0.0
MIDlet-1: HelloMidlet,,HelloMidlet
MicroEdition-Profile: MIDP-1.0
MicroEdition-Configuration: CLDC-1.0

At this point, let’s create a compressed JAR file of the classes that make up the MIDlet. With the manifest and the preverified class in the same directory, enter the following command:

>jar cvfm HelloMidlet.jar manifest.mf HelloMidlet.class

Once that is completed, you’ll need to create the JAD file. Example 4-6 shows the JAD file for our HelloMidlet application. Note that we had to change the value of the MIDlet-Jar-Size attribute to match the size, in bytes, of the JAR file that we just created. In this case, it turned out to be 954 bytes with the additional manifest information.

Example 4-6. HelloMidlet.jad

MIDlet-1: HelloMidlet,,HelloMidlet
MIDlet-Jar-Size: 954
MIDlet-Jar-URL: http://www.oreilly.com/
MIDlet-Name: HelloMidlet
MIDlet-Vendor: ORA
MIDlet-Version: 1.0.0
MIDlet-Description: A sample application

Now we’re ready to go. Again, be sure that the JAD file and the JAR file have the same name and reside in the same directory. Then use the iDEN software tools to download the application to your phone. It should only take a few seconds once you’ve chosen the target JAD file. After the download has completed, start the Java Application Manager on the phone (Java Apps under the Main Menu) and select the HelloMidlet application. Press the soft button to install it. You are now installing your first Java MIDlet on a real device. If everything goes okay, you can run your program after it completes the installation and verification steps.