alm OS-based handhelds and smartphones are powerful, pervasive computing devices that have changed the lives of many users through the applications they house. As a Java developer, why not tap into this widely used platform? You can develop applications for Palm and this article shows you how. Learn how to create a small Java application (more specifically, a MIDlet) and deploy it to an emulated Palm device. The instructions assume that you are familiar with MIDlet programming.
To create a J2ME application for the Palm OS, you need to convert your MIDlet to a PRC (Pilot Resource Code). This article first walks you through the creation of a simple MIDlet and then onto the MIDlet-to-PRC conversion.
Set Up Your Palm OS Emulator
Before you begin programming, set up an environment that emulates the Palm-powered handheld. Download the PalmOS Emulator, Palm OS Emulator Skins, and the ROM images. In order to download these, you need to join the Palm OS Developer Program (a free process). The Palm OS Emulator is available for Windows, MacOS, and Unix. The emulator download includes a PDF document “Using Palm OS Emulator” that breaks down how to install and use the Palm OS emulator.
To get started, unzip the emulator and ROM zip files into a directory of your choice. Unzip the skins file to a subdirectory called Skins under the directory you created and then run Emulator.exe. Next, choose the option to start a new emulator session, as shown in Figure 1.
 |
| Figure 1: Starting a New Emulator Session |
In the subsequent New Session screen (see Figure 2), use the GUI to point to the ROM file that you extracted.
 |
| Figure 2: Pointing the Session to a ROM File |
After pointing to the ROM file, you will see which devices are supported under the ROM file (see Figure 3). Also, pick a Skin that you would like to use. I chose the Standard-English Skin as shown in Figure 3. Next, click OK.
 |
|
| Figure 4. The Palm Emulator |
 |
| Figure 3: Specifying More Options for Your Emulator Session |
At this point, you should see the emulator running as shown in Figure 4.
The emulator you see runs Palm OS. To run Java programs, a Palm device (emulated or the real thing) needs to have a J2ME application runtime environment installed. You will install one next. Keep the Palm emulator running for now.
Install the MIDP for Palm OS Application Runtime Environment
 |
|
| Figure 5. Installing MIDP for Palm on the Palm Emulator |
MIDP for Palm OS is a Java runtime environment for Palm OS handhelds that enables a device running the Palm OS to run a J2ME application. The MIDP for Palm OS Version 1.0 runtime environment is compliant with the Connected Limited Device Configuration (CLDC) 1.0 specification as well as the Mobile Information Device Profile (MIDP) 1.0 specification.
 |
|
| Figure 6. The Newly Installed Java HQ Palm Application |
Download the MIDP for Palm OS zip file and extract it into a directory on your hard drive. The directory should contain a subdirectory named midp4palm1.0PRCfiles. Navigate to that directory and look for the file called MIDP.prc. To install MIDP for Palm onto the emulator, drag and drop the MIDP.prc file to the emulator as shown in Figure 5.
 |
|
| Figure 7. About Java HQ |
To install MIDP to a real Palm device, you would simply use the Palm Install tool and then synchronize your PC with your Palm device.
Your installation efforts should show a new Java HQ icon (see Figure 6).
Clicking on the Java HQ icon gives you some background information about Java MIDP (see Figure 7).
 |
|
| Figure 8. Installing the Sample MIDP-based Games |
To test out your J2ME Palm setup, you can drag and drop the file Games.prc onto your emulator just as you did the MIDP.prc file. You will install some games that are MIDP-based Java applications as shown in Figure 8.
Double click on the Games. You should be presented with a Sun Microsystems Binary Code License Agreement. Read through the agreement and click the Accept button (you will need to accept the agreement only for the first time you run a MIDP-based application on your Palm device).
If your Java MIDP environment was installed properly on your Palm, after accepting the agreement you should be asked to choose a game (see Figure 9).
 |
| Figure 9: Verifying the MIDP Environment Was Correctly Installed on Your Palm |
 |
|
| Figure 10. Pointing the J2ME Toolkit Install to Your J2SDK Install |
At this point, click the Home button on your Palm. With your Java runtime environment installed, you are now ready to create a Java application that you’ll deploy to your Palm (emulated) device.
Obtain and Install the J2ME Wireless Toolkit
Although not a full J2ME tutorial, this section does provide a quick overview of what you have to do to create a simple MIDlet. You need to have the J2ME Wireless Toolkit installed. You can download it from java.sun.com (at the time of this article’s writing, the toolkit was in version 2.2). The toolkit requires that you have the Java 2 SDK (J2SE SDK), version 1.4.2 installed. During the toolkit install, you will be asked to point to the J2SE install directory as shown in Figure 10.
Create a Simple J2ME Application
For demonstration purposes, create a small J2ME MIDlet that displays the current time when you invoke it on your Palm device. The following is the code for this simple J2ME application (click here to download a zip file of this code):
package com.j2me.example;import javax.microedition.midlet.*;import javax.microedition.lcdui.*;import java.util.Calendar;public class TimeTeller extends MIDlet { private Display display; TextBox box=null; public TimeTeller(){ } public void startApp() { Calendar now = Calendar.getInstance(); int hours = now.get(Calendar.HOUR_OF_DAY); int minutes = now.get(Calendar.MINUTE); if (hours==0) hours+=12; display=Display.getDisplay(this); String message = "The time is "; message+=hours+":"+minutes; box=new TextBox("Simple Example", message, 20, 0); display.setCurrent(box); } public void pauseApp() { } public void destroyApp(boolean b) { }}Place the above code in a file named TimeTeller.java under the directory structure:
javac –bootclasspath libcldcapi11.jar; libmidpapi20.jar comj2meexampleTimeTeller.java So for example, if your J2ME wireless toolkit installation directory is c:wtk22 (i.e., the default), then your command would look like the following:
javac –bootclasspath c:wtk22libcldcapi11.jar; c:wtk22libmidpapi20.jar comj2meexampleTimeTeller.java[Author Note: The remainder of the article assumes that the J2ME toolkit was installed in c:wtk22. If this is not the case for you, modify the commands accordingly.]
Notice the inclusion of cldcapi11.jar and midpapi20.jar to your bootclass path during compilation. By specifying this compilation option, you are telling your JDK to use J2ME libraries so you don’t inadvertently pick up J2SE classes during your compilation. The compilation should produce a TimeTeller .class file in your comj2meexample subdirectory.
Next, you need to preverify the class you produced so that it can be run on a J2ME target device. Without delving too deeply into the science of J2ME, you perform preverification because you do not have the luxury of intense bytecode verification in your J2ME device’s virtual machine. From the parent directory of the TimeTeller class, run the following preverification command:
c:wtk22inpreverify -classpath c:wtk22libcldcapi11.jar; c:wtk22libmidpapi20.jar com.j2me.example.TimeTellerThis command should produce a directory called “output”, which is under the packaging directory structure comj2meexample. In this subdirectory, you should find the preverified version of the TimeTeller.class with the same name (TimeTeller.class).
Next, you need to package your class as a JAR file. The JAR file must contain a Manifest file that describes your MIDlet. In the output directory that was automatically created in the preverification step, create a file named Manifest.mf with the following text in it:
Manifest-Version: 1.0MIDlet-1: TimeTeller, , com.j2me.example.TimeTellerMIDlet-Name: TimeTellerMIDlet-Version: 1.0MIDlet-Vendor: Kulvir BhogalMicroEdition-Configuration: CLDC-1.0MicroEdition-Profile: MIDP-1.0(Note that a new line after the last attribute must be present. Otherwise, this attribute will not be recognized.)
Create the JAR file with the following command issued from the output directory:
JAR cvfm TimeTeller.jar Manifest.mf .comIssuing the command above should yield something like the following:
added manifestadding: com/(in = 0) (out= 0)(stored 0%)adding: com/j2me/(in = 0) (out= 0)(stored 0%)adding: com/j2me/example/(in = 0) (out= 0)(stored 0%)adding: com/j2me/example/TimeTeller.class(in = 1307) (out= 705)(deflated 46%) |
|
| Figure 11. Pointing the J2ME Toolkit Install to Your J2SDK Install |
For a J2ME device to be able to use the JAR file you just produced, you also need to create a Java Application Descriptor (JAD) file. Create a file named TimeTeller.jad in the output directory with the following content:
MIDlet-Name: TimeTellerMIDlet-Version: 1.0MIDlet-Vendor: Kulvir BhogalMIDlet-Description: Simple J2ME ProgramMicroEdition-Profile: MIDP-1.0MicroEdition-Configuration: CLDC-1.0MIDlet-1: TimeTeller, , com.j2me.example.TimeTellerMIDlet-Jar-URL: TimeTeller.jarMIDlet-Jar-Size: 1603 |
|
| Figure 12. Trying TimeTeller Out on Sun’s MIDP Emulator |
Pay particular attention to the name value pairs of options that exist in both the JAD file and the Manifest file you created earlier. Also, notice the MIDlet-Jar-Size name value pair. You will need to set the value of this option to the number of bytes that your TimeTeller.jar file takes on your machine. In my case, this was 1,603 bytes, as shown in Figure 11.
At this point, make sure that your J2ME application works as expected using the J2ME Toolkit’s built-in emulator. Issue the following command from your output directory:
C:wtk22inemulator –Xdescriptor:TimeTeller.jadDoing so should yield your J2ME application deployed to the Sun’s MIDP emulator as shown in Figure 12.
Convert from MIDlet to PRC
 |
|
| Figure 13. Launching the PRC Converter Tool |
So far, you have created a MIDlet deployable to a J2ME device. However, the Palm OS can’t readily invoke a MIDlet. You must convert your MIDlet to a PRC file. The PRC Converter Tool, which was installed when you extracted the MIDP for Palm OS zip file, handles this for you. Look in the directory you extracted the zip file into for a directory called midp4palm1.0Converter. You should find a batch file named converter.bat, which assumes that you have an environment variable named JAVA_PATH set to your Java installation directory. If you don’t, create such an environment variable and then invoke the batch file. Doing so will launch the PRC Converter Tool (see Figure 13).
 |
|
| Figure 14. The Convert Option of the PRC Converter Tool |
To convert your TimeTeller MIDlet to a PRC file, you simply need to use the File>Convert option in the PRC Converter Tool (see Figure 14).
In the following “Choose your JAD files” window, point to the TimeTeller.jad file in the output directory you created and click the Convert button as shown in Figure 15.
 |
|
| Figure 15. Choosing a JAD File |
Doing so should produce a Success message as shown in Figure 16.
All you have left is to drag and drop the TimeTeller.prc file you just produced onto the Palm OS Emulator (or if you are deploying to a real Palm device, use the Palm Install Tool and perform a synchronization operation). Either way, you should see the TimeTeller application installed to your target device as shown in Figure 17.
 |
|
| Figure 16. Successful Conversion of the MIDlet into a PRC |
Clicking the TimeTeller application should yield the fruits of your labor: your MIDlet running on your Palm as shown in Figure 18.
 |
|
| Figure 17. Confirming Installation of the Time Teller PRC |
Your Door to the Pervasive Computing Space
Now you know how to create a J2ME application in the form of a MIDlet and transform it into a PRC file that is deployable to a Palm device. The MIDlet you deployed to Palm in this article was quite simple, but you can create more powerful MIDlets that tap into the offerings of J2ME, including games and mission-critical enterprise applications that use Web services (see Turn Your J2ME Mobile Devices into Web Service Clients).
 |
|
| Figure 18. Output of the TimeTeller Application Invoked on the Palm |
As Palm platform users represent a significant portion of the pervasive computing space, being able to cater to them by simply porting your new and existing J2ME MIDlets as PRCs opens the door to a much larger audience with little coding effort.
