Building a Java ME CDC Application Using the SavaJe Phone

If you were at JavaOne this year, you couldn't have missed the new all-Java mobile phone platform announced by SavaJe. Along with the platform, they made available a developer's edition of a new phone based on SavaJe, called the Jasper S20. The phone was named "device of the show" for JavaOne 2006.

Of course, for a Java developer, the most interesting aspect of the device is that nearly all of the platform is itself written in Java. Because all of the phone's services, applications, and APIs are in Java, it is that much easier to write compelling applications that take advantage of the device's capabilities and provide features that users expect.

Java Micro Edition JSR Soup

Java ME has been running on phones for quite some time now, starting with hardware that was barely capable and evolving as technology improved. With each new step in platform capabilities, there were JSRs to specify the corresponding Java APIs. The SavaJe platform is no slouch, and implements so many of these JSRs that I can only list a few.

The more limited collection of APIs that most phones implement revolve around the Connected Limited Device Configuration (CLDC) and the MIDP profile, with Midlets being the unit of application deployment. SavaJe implements the following JSRs in CLDC mode, primarily defined by JSR-185:

Now, even more interesting is the Connected Device Configuration (CDC), with Swing Xlets being the unit of application deployment. SavaJe is unique as a phone platform in providing so much functionality to Java developers. Just take a look at all these goodies!

This article will focus on Xlets and AGUI. Xlets will give you the means of deploying your application and controlling its lifecycle; AGUI will give you the APIs to create a snazzy look.

Java ME CDC Tools

The most conventional approach to developing Java ME is to use a phone platform emulator combined with plugins for an IDE. For SavaJe as well as any other CDC device, Sun provides a CDC Toolkit that contains the emulators and libraries, along with the Mobility Pack for CDC for NetBeans 5.5. This is a nice package, and provides a turnkey development cycle.

Related Articles

Unfortunately, Sun's CDC Toolkit is only available on Windows, which is a problem for me because I have only Mac and Linux machines available. Although it is possible to pull pieces out of the toolkit and assemble a working environment, I chose to drop down to the metal, creating the necessary bundles by hand and developing in my preferred IDE: Eclipse. Yes, I can hear the Sun engineers gnashing their teeth, but you can't knock an approach that works, and until the CDC Toolkit works on Mac or Linux, this is the best option.

About the Application

I hunted around awhile, trying to think of an interesting killer application to write for the SavaJe. There are so many possibilities given the rich APIs, but in the end I thought I'd pick something small, fun, and easy to get started. I've been hooked on the puzzle game Sudoku recently, and thought the phone display and keyboard would make perfect interfaces. (And allow me to sneak in play time almost anywhere.) The application that you'll build is a simple Sudoku playing GUI that allows predefined puzzles to be solved using the phone's joystick and number keys.

The display, living in a desktop testing frame, looks like this:

and is implemented using a simple JPanel and Java 2D methods. The yellow square indicates the selection where numbers are entered using the number pad, and is moved using the joystick that sends arrow key events.

Adding puzzle generation, fancier game play, and wizzy graphics is something I'll have to leave to a future time. In this article, I'll keep it simple and focus on the details of getting Xlets running on the phone. All of the source code for this application is available as open source on Google Code. Follow the directions there to check out the project source.

Setting Up the Development Environment

The first thing you'll need to get started is Eclipse. You can download Eclipse 3.2.1 for your OS. Versions are readily available for Windows, Mac, and Linux. Install it in the default location with default settings. No special plugins are required, but one easy way to get the project source is to use the Subclipse plugin that can be found at http://subclipse.tigris.org/.

The next thing you'll need is the SavaJe libraries, bundled into the one: jar SavaJeDeveloper.jar. These are provided on the developer CD that comes with the phone, or can be downloaded from saveje.com once you've registered as a developer.

Organizing the Projects

To simplify development, and make testing easier, I have broken the application down into four small projects:

sudoku-eng: The "engine" that knows how to load and save games

sudoku-ui: The core UI written using portable Swing/Java 2D. Depends on sudoku-eng.

sudoku-se: A Java SE-based main and frame to help with testing. Depends on sudoku-ui.

sudoku-xlet: The Xlet-based application and frame for the phone. Depends on sudoku-ui.

This is how they look in the Eclipse project pane.

Building and running sudoku-se runs the Java SE application main() that creates a Swing frame for testing. This is a quick and easy way to try out new game features on the desktop without the overhead of deploying to the phone.

Building sudoku-xlet creates all of the Java binaries needed to run on the phone. The last few Xlet bundling steps are done by using a shell script to zip up the classes from the three projects into a jar, and copy it and other files into the right layout for deployment.

Each of the projects has a src folder for the Java and other sources. Here, you can see the two additional files needed for Xlets: bundle.jnlp, which controls the bundle contents and startup class; and bundle.policy, which requests security permissions for the bundle. I chose to name the Java packages to match the project names to make things easier to remember, but this is not critical.

One thing that is crucial, though, and all too easy to overlook, is that the phone only supports Java 1.4.2.

Note: If you build against Java 1.5 libraries or use the Java 5 compiler setting, really bad things will happen and your Xlet will mysteriously refuse to start. You must set the compiler to 1.4.2 and select the 1.4.2 JRE to build against.

A Bundle of Xlets

The building, bundling, and deploying of an Xlet for SavaJe is refreshingly simple. The first step is to create an Xlet bundles directory on the phone's SD memory card. The next step is to create a sub directory under that for each Xlet. When the SD card is inserted into the phone, all of these Xlets will become available under the "My Applications" section of the phone's menu. In your case, the tree looks like this:

/savaJe/bundles/
Sudoku/
bundle.jnlp
bundle.policy
lib/
classes.jar

The bundle.jnlp file is an XML file with a few interesting values that must be defined. For this application, the file looks like this:

The codebase attribute defines a URI that is cross-referenced in the policy file. The two uses must match, but are otherwise unimportant. The resources elements describe which JRE the application needs and where its jar lives. It can be left with the default values shown above for most applications. The information elements should be filled in for your application and are pretty self-explanatory. These may be shown to the user when browsing installed Xlets. Finally, the application-desc element indicates which class in the jar is the actual Xlet to launch.

The bundle.policy file is a standard Java policy file for the Xlet. For this application, you simply request full permissions for all classes in the jar.

You can see where you first aggregate all of the classes under staging so that they can be zipped together into classes.jar. The jar plus the two bundle files then get copied into the dist tree. The final step of deploying to the phone is to simply copy this tree to the phone's SD card. I use this one-liner:

cp -R dist/* /Volumes/PHONESD/savaJe/bundles/Sudoku/

You'll likely need to adjust the paths to fit your system setup and the volume name of your SD card.