Building and testing J2ME MIDP applications with the Wireless Toolkit

Building an MIDP application requires a little extra work. Web editor Lamont Adams explains the necessary steps and introduces you to a free tool that can automate them for you.

In a previous article, I introduced you to a simple Java Micro Edition (J2ME) application for the widely used Mobile Information Device Protocol (MIDP). In that article, I alluded to the fact that the steps you need to take to compile and deploy an MIDP application differ from those used to deploy a typical Standard Edition application. Let's examine those steps and take a look at a free tool from Sun that helps you manage the process of creating and testing MIDP applications.

Get what you need
If you don't have it already, you'll want to download and install the reference implementations of the Connected Limited Device Configuration (CLDC) and MIDP, which include the packages and command-line tools you need to build a J2ME application, and a selection of emulators you can use for testing your work. You'll also want to download the J2ME Wireless Toolkit from Sun, which can be integrated into the Forte IDE or used as a stand-alone tool. The Wireless Toolkit provides a nice GUI interface for the command-line tools you'll need, as well as some rudimentary code management and configuration tools.

Using the Wireless Toolkit
So what's the big deal here—what's so different about building for J2ME? Remember that MIDP devices will by and large have very limited memory (this is quite a recurring theme, isn't it?), so some concessions had to be made in the runtime support offered on the platform. The big difference from a building and deployment point of view is that there is no runtime class verifier for the MIDP implementation. After the code is compiled and before it can be run on an MIDP device, it must be preverified using the Preverify.exe tool. In addition, a completely different set of class libraries and startup files must be included via a command-line switch to the Java compiler. The Wireless Toolkit, shown in Figure A, knows how to perform these extra steps so that you don't have to.

Figure A—The Java Wireless Toolkit
It's called KToolbar. Don't ask me why.

Building an application with the Wireless Toolkit consists of five basic steps:
  1. 1.      Start the toolkit, which is easier said than done. Look for the program called KToolbar if you're lost, which you probably will be your first time.
  2. 2.      Create a new project using the Create Project button. You'll be prompted to provide the name of the project as well as the name of the main MIDlet class that should be run to start the application. The toolkit will create a project directory for you using the project name you provide.
  3. 3.      Verify that the project properties you are shown are correct. We'll go over these in a minute.
  4. 4.      Write your Java source in your favorite editor or IDE (or copy existing code) and save into the src subdirectory under the main project folder.
  5. 5.      Build your application using the Build button and use the Run button to test it in the device emulator of your choice. You'll have to download a ROM image for the Palm device emulator, but the others are included in your MIDP and CDC implementations.

Would you like a suite?
MIDP applications are organized into suites, which may contain one or more MIDP applications. Each MIDP suite is distributed in the form of a Java Archive or JAR file (which the Wireless Toolkit can create for you using the Project | Package menu command). If you've done any serious Java development before, you're probably already familiar with the idea of a JAR file. If not, you might want to read up on them at Sun's official Java Web site. Every JAR has what's known as a manifest, which provides information about the classes contained in the file. The Project Settings dialog box you see immediately after creating a new Wireless Toolkit project lets you define the contents of this manifest file. Manifests support a set of nine attributes, six of which must be defined for every MIDP application. These required attributes appear in Figure B.

Figure B—Required JAR manifest attributes
You gotta have at least these.

A Java Application Descriptor (JAD) file may also be provided for an MIDP suite. The JAD file houses additional configuration information about an application and can be accessed by an application at runtime using the MIDlet.getAppProperty method. Think of JAD files as text-based configuration files (a Windows INI file is a good analogue), and you've got the basic picture. Like JAR manifests, JADs also have a set of six required attributes. These are listed in Figure C.

Figure C—Required JAD attributes
Some of these should look familiar.

You'll notice that some attributes are required to be in both files. The values provided for these duplicate attributes must match each other exactly. Otherwise, the application manager will refuse to load the suite. While the Wireless Toolkit takes care of this for you, you should keep this fact in mind should you ever need to edit a JAR manifest or JAD file by hand.

Building your first MIDP application
If you'll recall, I gave you the code for a simple "Hello World" application in my previous article. Relax—you don't need to go fumbling for it now, I put it in Listing A. Let's walk through the process of building and running an application using the Wireless Toolkit.

First, create a new project and name it HelloJ2ME. The name of the MIDlet should be HelloJ2ME as well. You'll then see the dialog box that lets you specify attributes for the JAR and JAD. The default settings shown in Figure D should be correct and should be sufficient to create a working application.

Figure D—Project settings for HelloJ2ME
Your settings should look like this.

After you provide the project settings, the toolkit will create a project folder for you and instruct you to place the source code in the src subfolder. Save the code from Listing A as in that subfolder and then click the Build button. Assuming my code is correct (which is somewhat dependent on my caffeine level the day I wrote it), it should compile without complaint. You can then click Run and select HelloJ2ME from the application menu shown in the emulator (just click the button below Launch), to see the fruits of your labor run, as shown in Figure E.

Figure E—Running HelloJ2ME
Hello back at you.

The hardest part of this whole exercise will probably be figuring out how to use the emulator. Look for the buttons below the phone's LCD screen; they'll execute the command shown immediate above them on the screen.

Figure E shows the default DefaultGreyPhone emulator, but you can select a different emulator using the Device combo box in the toolkit's main window. Most of the emulators will have command buttons somewhere that operate similarly to the ones below the screen on DefaultGreyPhone. It may take some exploration, but if you look for the white highlight that identifies something as a button when you mouse over it in the emulator, you'll eventually find them. Just don't ask me how to use the Blackberry RIMJavaHandheld emulator, I haven't figured that one out yet.

Now that we've got the basics down, I'll follow up via a few future articles to walk you through an application that's a bit more complex. Until then, happy coding.


Editor's Picks