Introduction

This is a quick and dirty guide on how to program in Java for PalmOS 5, for PalmOne handhelds. It is a process that I found very poorly documented, hence this guide. This may work with other PalmOS 5 handhelds, but bear in mind that it's PalmOne (along with IBM) and not PalmSource that is providing the java runtime. In short, there may be some PalmONE specific aspects here. Moreover, this guide assumes that your development machine is running Linux. It should be quite similar for Solaris (apart from compiling the PRC) and bit different in setting up the environment under win32.

Which Java

PalmOne/IBM provide a version of J2ME, the cldc 1.1 configuration and midp 2.0 profile. Actually, the public release (for users) only supports cldc 1.0 and midp 1.0 - support for 1.1 and 2.0 respectively is in beta and only available for the developper release.

Rant

That's right J2ME, CLDC - Connected Limited Device Configuration. Whereas other handhelds have had PersonalJava, CDC and even the full J2SE available for a number of years now, PalmOne/IBM in an incredible PR Stunt release only a KVM, supporting only the CLDC - Your brand new £400 PalmOne Tungsten T3 (complete with 64MB of RAM and a 400MHz Xscale processor) which is quite a bit more powerful than the aforementioned handhelds can only run a JVM destined for mobile phones. Hopefully, only the OS Limitations keep PalmOne/IBM from releasing a CDC-compatible JVM and the long awaited PalmOS 6 Cobalt will fix those. But I digress...

What you Need

Setting up the development environment

Setting up the J2ME Wireless Toolkit

This is rather straight forward. Execute the binary that you downloaded. You don't need to be root. Select your J2SE and installation directory during installation. We need to set up the programming environment. Lets assume that you're running bash (modify appropriately for other shells) and that you installed in $J2MEWTK_HOME. I have the following on my .bash_profile 
export MIDPAPI=$J2MEWTK_HOME/lib/midpapi20.jar
export J2MECLASSPATH=$J2MEWTK_HOME/wtklib/kenv.zip:$J2MEWTK_HOME/wtklib/kvem.jar:$J2MEWTK_HOME/wtklib/lime.jar:$J2MEWTK_HOME/lib/cldcapi10.jar
export PATH=$PATH:$J2MEWTK_HOME/bin

JAR to PRC

Uncompress the Websphere Micro Environment Toolkit for Palm OS. Go to IBM/"Websphere Micro Environment"/bin. Verify that jartoprc.exe runs under WINE: (wine ./jartoprc.exe). Configuration of WINE is considered to be out of scope of this document.

Writing and Compiling Hello World

This is going to be a very brief section on how to write and compile hello world. This document is not meant to be an introduction to J2ME or the CLDC.

HelloWorld.java

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

public class HelloWorld extends MIDlet {

    private Display display;
    
    TextBox box=null;

    public HelloWorld() {

    }

    public void startApp() {
	display=Display.getDisplay(this);
	box=new TextBox("Example", "Hello World", 20, 0);
	display.setCurrent(box);
    }


    public void pauseApp() {

    }

    public void destroyApp(boolean b) {
	
    }

}
Create a directory called "tmpclasses". We will put our compiled but unverified class there. Perform the compilation by issuing
javac -g:none -d tmpclasses -bootclasspath $MIDPAPI -classpath $J2MECLASSPATH HelloWorld.java
The class should have compiled correctly.

Create a directory where you'll put the actual preverified classes (say classes), and then preverify:

preverify -classpath $MIDPAPI:$J2MECLASSPATH:tmpclasses -d classes tmpclasses Go to the classes directory and create the following files:

MANIFEST.MF

MIDlet-1: Hello,,HelloWorld
MIDlet-Name: HelloWorld
MIDlet-Version: 1.0
MIDlet-Vendor: TES
MIDlet-Jar-URL: HelloWorld.jar
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-2.0
Create a jar file:
jar cvf HelloWorld.jar -m MANIFEST.MF HelloWorld.class Find out the size of that file (by doing, say ls -l HelloWorld.jar.

Create the following file:

HelloWorld.jad

MIDlet-1: Hello,,HelloWorld
MIDlet-Name: HelloWorld
MIDlet-Version: 1.0
MIDlet-Vendor: TES
MIDlet-Jar-URL: HelloWorld.jar
MIDlet-Jar-Size: 874
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-2.0
Note that the MIDlet-Jar-Size should be equal to the size of your jar file.

Test your application

If all went well, you should be able to run the application:

emulator -Xdescriptor:HelloWorld.jad
You should see something similar to the screen on your right. Time to set up the palm!

Setting up your Palm Handheld

From the Websphere package, install the following files to your palm: IBM/"Websphere Micro Environment"/prc/ARM/J9JavaVMMidpNG.prc and IBM/"Websphere Micro Environment"/prc/IA32/midp20.prc (I understand that the IA32 bit sounds dogdy - it sounds dodgy to me too). Done! Time to test the application on the palm.

Testing on the Palm

You need to turn your jar&jar files into a palm PRC - To do that, use the jartoprc.exe utility under WINE. Don't forget to have come up with a creator ID, otherwise jartoprc.exe will assign one for you. Transfer the resulting prc on your palm, and it should show up on your launcher.

Final Thoughts

I just thought that the process above was horribly documented - I hope to have done a better job at it. If you're running windows you can use websphere directly, although I cannot comment on that as I haven't done it myself. Note that you can also use ktoolbar from the Wireless Toolkit to save you some compilation trouble. Finally, it is unfortunate that PalmOne has started using Simulators; and that they only support win32 for them...
Stefanos Zachariadis
Last modified: Tue Feb 17 18:15:49 GMT 2004