Configuring Java (J9) on a Pocket PC with RMI and SWT using CDC Personal Profile: some experiences and issues

This page presents some tricks, configurations and workarounds applied by me when configuring a pocket PC (WindowsME 2003) to run Java (IBM J9 virtual machine). I was particularly interested in running SVG and SWT in the pocket PC in order to support a tiny version of Impromptu desktop application. However, I could not run SVG (apache Batik) since it required Swing, which is not supported by the personal profile of Java. Then, I proceeded to use a TinySVG implementation from TinyLine which claimed to run on those devices. My success in running TinyLine was partial (the examples ran but extensions implemented by be did not). This document also presents my experiences on installing the other components. Currently, I dropped SVG, SWT and other approaches, and I am using AWT to develop RMI applicatoins in the PocketPC.

Introduction

J9 is an implementation of J2ME (Java 2 Mobile Environment) that supports different profiles. Each profile is developed for a different kind of device, ranging from very limited resource devicess such as cell phones, to more powerful devices such as pocket PCs. For a comparison of the differences between those profiles, and JDK1.3 go to: CDC API Comparison. And, for a description of the different profiles go to : J2ME Documentation.

The Pocket PC I used was a Dell AIXM running WindowsCE 2003. It supports the use of the Connected Device Configuration Personal Profile (CDC-PP in short), which is one of the profiles that most resembles JDK1.3. In fact, the CDC-PP is a stripped off version of the JDK1.3 java runtime environment. It does not include, for example, packages like java.rmi or javax.swing. Hence, in order to have RMI support (necessary to run YANCEES, a pub/sub component in the Impromptu application), we will need to install the optional java.rmi support as further described in this document. For the GUI, instead of swing, which is also not supported by the CDC-PP, we will use a port of SWT for Pocket PC provided by the eclipse project.

The good news is that because the CDC Personal Profile is so close to JDK1.3 (desktop version of java), you can use your favorite IDE to develop your applications. Hence, you with no need of specialized compilers. The code compiled for JDK1.3 should run without modification in your PocketPC provided that you do not use in your code any library that is not included in this profile, such as swing, for example; and any new language extension, such as those provided in JDK1.5. For example, in this project, I used Eclipse.

Setting up a development environment on your desktop PC and PocketPC

In order to develop applications for the Pocket PC, one needs to set up an editor (or IDE) for the application development, and a way to download and run those applications in the PocketPC. The good news about Personal Profile is that you can use any editor and IDE, with a JDK1.3 compatible java compiler in your desktop. As for the PocketPC, Microsoft provides a nice set of utilities, which come as part of the Windows Mobile Developer Power Toys, including a command processor, similar to a DOS prompt, and a remote control program (ActiveSync Remote Display) that allows you to control your pocket PC from the desktop (via craddle or USB cable). After following the link above and installing the Microsoft Movile Developer Power Toys on your desktop computer, copy the contents of the command prompt software located at: C:\Program Files\Windows Mobile Developer Power Toys\PPC_Command_Shell from your desktop to your pocket PC, maybe in a directory called \opt\cmd. This will allow you to start the cmd.exeprogram that implements the command interpreter. (tip: use the Explore button in your Microsoft ActiveSync application that comes with the PocketPC and do not forget to copy the console.dll file to your \Windows folder in the pocketPC).

The command interpreter will allow you to start .bat files and .exe applications in your PocketPC, including the j9.exe and the j9w.exe programs once they are installed in your mobile device. To run the command interpreter, just run the cmd.exe program.

Installing J9 Java Virtual Machine

The first step in the configuration of the java environment, is to download and install the IBM J9 virtual machine on your pocket PC. We will use the java J9 runtime evaluation version provided by IBM in the site: Websphere Everyplace Micro Environment. Download the WebSphere Everyplace Micro Environment 5.7.1 - Personal Profile 1.0 for pocket PC, which is a long name for the J9 java runtime. Follow the above link, download the program and install on your desktop PC. IBM provides installation guides in its download site. The installation program will install the J9 runtime environement under \Program Files\J9 directory on your Pocket PC.

You should also download a 30 day evaluation version of the whole IDE, the IBM Workplace Client Technology, Micro Edition 5.7, which includes porting of IBM J9 to different architectures, besides of the whole Java development environment (Click here for an alternative link). Obs. There is a License Not Found Bug in the installation of this software that requires you to set the date of your computer to May 1st 2005 in order to install it.

I suggest you to download and install both applications since you will need IBM Workplace Client Environment in order to download the RMI Optional package from IBM. However, if you just want the virtual machine, the first link will do it.

Downloading aditional components

In general, additional components, in the form of .jar files, can be installed in the J9 runtime environment by copying those files to the \Program Files\J9\PPRO10\lib\jclPPro10\ext directory in your PocketPC.

Install RMIOP. IBM provides RMI as an optional package (called RMIOP) that can be installed in the J9 runtime environment. In order to get this packages, you will need the IBM Workspace Client Technology, Micro Edition 5.7, an IDE from IBM, as described in the previous step. After installing this IDE, start the Device Developer environment from IBM. It uses Eclipse 2.0 as its base environement which you may be familiar with. Go to the Help menu and start the Update Manager. Click in Sites to Visit, and select IBM WebSphere Everyplace Device Developer Technologies/Technologies/WEME RMIOP (Runtime 2.2) and install the RMIOP optional package. The additional files will be added to each runtime environment under C:\Program Files\IBM\DeviceDeveloper\wsdd5.0\ive-2.2\runtimes in your desktop computer. Copy the new files to your pocket PC: since we are using the Personal Profile, copy the rmip.jar and rmip_nl1.jar (optional language pack), from C:\Program Files\IBM\DeviceDeveloper\wsdd5.0\ive-2.2\runtimes\wm2003\arm\ppro10\lib\jclPPro10\ext to the \Program Files\J9\PPRO10\lib\jclPPro10\ext folder in your pocket PC. This should add the RMI support to your J9 environment. The RMI is compatible with the JDK1.3 environment and suppots most of its features (with exeption of some advanced ones as dynamic activation and so on).

Install a new version of SWT. J9 already supports SWT. The file \Program Files\J9\PPRO10\lib\jclPPro10\ppro-ui.jar alreay comes with the org.eclipse.swt.* packages on it and the swt-win32-3050.dll is already present in the \Program Files\J9\PPRO10\lib\bin folder of your J9 installation. This version, however, is old and limited in the number of widgets it supports. Hence, you may want to install an updated and more complete version of SWT in your device.

In order to do so, you must download a new version of SWT and install its respective .jar and .dll files. The .jar file needs to be copied to the ext folder in the J9 runtime distribution in your pocket PC; whereas the .dll file needs to the copied to the bin folder. First, download the SWT for Windows CE (ARM PocketPC) from the SWT download website. Note that there are two versions, one for the CLDC and another for Personal Profile. You want the one for Personal Profile. The one I downloaded was swt-3.0.2-win32-ce-arm-ppc.zip (newer versions are posted regularly). Then, copy the swt.jar file from inside the distribution to \Program Files\J9\PPRO10\lib\jclPPro10\ext in your device, and the swt-win32-3064.dll or newer version to the \Program Files\J9\PPRO10\bin folder in your device. A description on how to use SWT in a pocket PC is described here: A small cup of SWT.

This procedure, however, will most likely conflict with the already installed swt-win32-3050.dll which comes with J9. If you erased this file, hoping that the new .dll would be used instead, the J9 virtual machine will throw an exception: "java.lang.UnsatisfiedLinkError:swt-32-3050". A possible solution to this issue is to add the new .class files from the swt.jar file to the ppro-ui.jar file that is in \Program Files\J9\PPRO10\lib\jclPPro10. For more details, see the discussion thread. Another, more elegant solution, is to change the J9 internal bootclasspath to include the new .jar file first in this path. To do so, you can use the -Xbootclasspath option. For example: "\Program Files\J9\PPRO10\bin\j9.exe" "-Xbootclasspath/p:\opt\swt\swt.jar". The /p key indicates to prepend the value to the path [Contribution from Peter Skopek].

Obs. If you made some mistake in this process, you can always restore the original J9 environment from your: C:\Program Files\IBM\DeviceDeveloper\wsdd5.0\ive-2.2\runtimes\wm2003\arm\ppro10\bin directory from your desktop computer.

OTHER PACKAGES

Install XML Support. In order to add XML: SAX and DOM support for your J9 Personal Profile environemnt, you can download Xerces 2 Java Parser and copy the xml-apis.jar, resolver.jar and the xercesImpl.jar files to \Program Files\J9\PPRO10\lib\jclPPro10\ext in your device.

Install SVG. There is a light version of SVG graphics engine for Pocket PC at: TinyLine SVG web site.

Running your applications

Java command. There are two ways to use the J9 java virtual machine, by invoking j9.exe or j9w.exe. The first one is equivalent to java.exe in traditional J2SDK, the second is equivalent to javaw.exe in that desktop environment. The j9w.exe starts the application without generationg command line output. In other words, it starts scilently. For development purposes, j9.exe is better, since the exeptions will be displayed on the screen; while for final sofware releases j9w.exe is probably more indicated.

Use Full Path Names. In order to run applications in the pocket PC, you must always use full path file names in your applications. This includes the options and parameters to your java application. The pocket PC and the j9 virtual machie seem not to understand relative paths.

Quotes. The path names, jvm option keys and the java application name must be written under " "s.

Shortcuts. For, example, to run a Hello World application you can create a windows link file and change its content to look like:
255#"\Program Files\J9\PPRO10\bin\j9.exe" "-jcl:ppro10" "-cp" "\opt\SWT\" "HelloWorld"

Parameters. In this example, the HelloWorld.class file is located at \opt\SWT\ directory. The parameter "-jcl:ppro10" indicates to J9 which profile to use for its execution, in this case the personal profile. The current directory is provided as the classpath. This is necessary, since the HelloWorld.class file is located in the \opt\SWT directory. The additional packages, installed in the ext folder of J9 runtime are automatically part of the classpath and do not need to be passed to the -cp parameter. The "255#" part in the begining of the link file indicates the size of the command line in bytes. This seems not to work well in the Windows CE 2003, though: more than 255 characters are ignored.

Use .bat files. Alternatively, you can create a .bat file, similar to the ones you use in regular windows desktop, and add the line above with the exception of the "255#" part. In order to execute .bat files, however, you need to be funning the cmd.exe application you previously installed in Microsoft Power Toys.

Here it is an example of a .bat file that runs a YANCEES publish client.
"\Program Files\J9\PPRO10\bin\j9.exe" "-jcl:ppro10" "-cp" "\opt\RMI\Yancees-SNAPSHOT.jar;\opt\RMI\" -D"java.security.policy=file://opt/RMI/java.policy.all" -D"java.rmi.server.codebase=file://opt/RMI/Yancees-SNAPSHOT.jar" "RMIPublisher" "bahia.ics.uci.edu" "/opt/RMI/event.xml"

The programs are installed in the /opt/RMI directlry. A java.policy.all file is also provided in this directory, with the security options used by this java virtual machine. All the RMI sbubs are in the Yancees-SNAPSHOT.jar file in this directory. Note that the jar file needs to be passed as part of the -cp parameter. The program RMIPublisher is started with two parameters: "bahia.ics.uci.edu" and "/opt/RMI/event.xml"

The command line above is the content of the file rmipub.bat which can be executed from within the cmd.exe command processor, after changing to the /opt/RMI directory. Note that the way you use RMI is the same as that implemented by JDK1.3.

The souce code of the examples previously discussed are available here: CDCDemo.zip

For further recerence, a pretty good description on how to run Pocket PC java programs is provided here.

Some known issues with J9 and cmd.exe

Limited link command line length. It seems that the j9.exe command line cannot exceed 256 characters in length when used under links. If the length of the j9.exe parameters exceeds 256, the program execution may not succeed, some classes in the classpath may not be found or some parameters may be missed. I am not sure this is an issue with j9 or with the cmd.exe program I am using to run my applications, though.

Links seem not to work at all if their lenght exceeds 256 characters too. I did nto test this option thoroughly. The first parameter of a link indicates its lenght in characters. Try using #512 in the begining of the link.

A good strategy to deal with these problems is to put all .jar files in the \Program Files\J9\PPRO10\lib\jclPPro10\ext folder in order to reduce the size of the command line, including the -cp parameter. Another idea is to put all your application files in a single .jar file passed to the -cp parameter.

An Alternative Way: Java Applets

Instead of running your java program as an application, you can consider running it as an applet inside Internet Explorer for pocketPC. The Esmertec Jbed CDC Java Virtual Machine provides a java plug-in for this purpose.

NetFronnt for Pocket PC is a browser that supports Java and Flash.

The Insignia Solutions Jeode Java Runtime provides a plug-in for PocketPC Internet Explorer that allows the execution of Java Applets on this device. It seems that JeodeRuntime was discontinued and/or changed its name to Jbed CDC java runtime .

In all those runtime environments, however, one needs to figure out how to run Java RMI, besides the basic installation process, which goes beyoond this document purpose.

An alternative: Use AWT

J9 provides suport for AWT (event model and widgets compatible with JDK1.1), which allows the development of more traditional java user itnerfaces.

In special, one can use drawlets, a framework for drawing graphics on top of AWT.

Tuffle (Touchable Look & Fell Specification) is a toolkit used to customize the look and feel of AWT applications that run on PDAs.

Another alternative: Use SVG Graphics

TinyLine provides a nice SVG implementation designed to support Personal and MIDP profiles called TinyLine SVG API. It is based on a Java 2D implementation called TinyLine 2D. One can use it to design graphic-intensive applications and visualizations.

Further References

Setting up java on Pocket PC:
Java Pocket PC, the Unofficial FAQ
Using Java on the Pocket PC - the complete tutorial
A brief adventure in "On-board Java Development" for Pocket PC 2002
Installing the J9 JVM run-time environment on a Windows CE device
Java for PocketPC PDAs

RMI on Pocket PC:
Sun Community Source Licensing(SCSL) - J2ME RMI Optional package (RMI OP)

Differences in the java profiles:
Understanding The Connected Device Configuration (CDC)
Eric Giguere's Personal Basis Profile vs. Personal Profile: What's the Difference?
Sun's Programmer's Guide, J2ME Personal Profile v1.0 [PDF]

Pocket PC java user interface links:
A small cup of SWT
Getting Started with Eclipse and the SWT
TinyLine SVG
Drawlets
J2MEPolish

Other Java Virtual Machines

Mysaifu JVM (GNU Public License v2)

Research Staff: Roberto Silveira Silva Filho
Professor: David F. Redmiles
Institute for Software Research
Information and Computer Science
University of California, Irvine CA 92697-3425

This page was last updated on November 15th, 2005 by Roberto S. Silva Filho