ONJava.com    
 Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples


What's J2ME?

by Daniel A. Tauber
03/08/2001

Java 2 Micro Edition (J2ME) is Sun's version of Java aimed at machines with limited hardware resources such as PDAs, cell phones, and other consumer electronic and embedded devices. J2ME is aimed at machines with as little as 128KB of RAM and with processors a lot less powerful than those used on typical desktop and server machines. J2ME actually consists of a set of profiles. Each profile is defined for a particular type of device -- cell phones, PDAs, microwave ovens, etc. -- and consists of a minimum set of class libraries required for the particular type of device and a specification of a Java virtual machine required to support the device. The virtual machine specified in any profile is not necessarily the same as the virtual machine used in Java 2 Standard Edition (J2SE) and Java 2 Enterprise Edition (J2EE). You'll see that the profile we'll use to develop a Palm OS device application is a subset of the Java Virtual Machine you already know.

To date, Sun has released the following profiles:

A profile in itself does not do anything; it just defines the specification. Profiles are implemented with a configuration. You can think of a configuration as an implementation of a J2ME profile for a particular type of device such as a PDA. Some of the configurations currently available are

Connected Device Configuration (CDC)

An implementation of the Foundation Profile for next-generation, consumer electronic and embedded devices

Connected Limited Device Configuration (CLDC)

An implementation of MIDP for small, resource-constrained devices such as Palm OS devices.

Since each profile defines a different set of Java class libraries, you cannot take a Java application written for one profile and run it on a machine that supports another profile. Likewise, you cannot take an application written for Java 2 Standard Edition (J2SE) or Java 2 Enterprise Edition (J2EE) and run it on a machine that supports J2ME. You can only use the Java classes provide in the Java class library included in your target device's profile. Restricting yourself from using all of the Java classes you've grown to rely on is one of the hardest parts of writing Java applications for small devices.

The rest of this article focuses on using the MIDP profile and CLDC configuration to create an application for a PDA running the Palm operating system.

Getting J2ME

The J2ME CLDC comes as two files that you can download from the Sun Community site. The first file is j2me_cldc_-1_0-src.winsol.zip and contains all of the class libraries needed to develop CLDC applications on your computer. In addition to containing the class libraries, it also includes both source code and Windows and Unix binaries for a reference implementation of the Java Virtual Machine specified by MIDP. This Java Virtual Machine is referred to as the K Virtual Machine (KVM), and its inclusion saves you the trouble downloading your applications to a handheld device during development. You can test them right on the same desktop machine you use for development.

The second file available from the Sun Community site is j2me_cldc-1_0-src-palm_overlay.zip, which contains an implementation of the KVM for devices running the Palm operating system, along with the tools to turn the .class file generated by a Java compiler into an executable Palm file. Note that this is a particular implementation of the CLDC for the Palm operating system. As other implementations become available, your Java application will be able to run on those other machines as well.

You'll need to install both of these ZIPs on your computer to develop applications for Palm OS devices. For the rest of this article, I assume you have these installed in the CLDC folder on the C: drive.

Note that you do not need a special Java compiler in order to develop CLDC applications. You use the compiler that comes with J2SE. The only difference is that you'll specify an alternative location for the class library during compile. You'll also need to process the resulting .class file with some special software included with the CLDC download.

Running the Sample Apps

The files you downloaded from Sun include both source and compiled versions of many sample applications. You can run these sample applications on your desktop computer using the KVM for Windows or Unix. Running these applications will let you get a feel of what a CLDC application is like. Before you can run these programs, you need to start a command shell and enter the following commands.

set cldc_classpath = c:\cldc\bin\api\classes;.
set bin = %bin%;c:\cldc\bin
cd \cldc\bin\samples\classes

Now that you have set up the environment variables and changed into the directory that holds the sample applications, you can start to run them. To run the UITest application, enter

kvm -classpath %cldc_classpath% UITest

Once you're done looking at the UITest application, you can take a look at the Pong game application by entering, at the the command line, the command

kvm -classpath %cldc_classpath% Pong

You can now go through and run each of the sample applications. Later you'll use the same method to run the sample application we'll develop on your desktop machine.

Building a Palm App

Now that you have a feel for the pieces that make up J2ME, let's move to actually building an application in Java to run on a Palm OS device. The first thing to realize is that just because J2ME is Java, that doesn't mean you can take your existing Java applications, re-compile them, and have them run on new devices. Key features found in the Java Virtual Machine used by J2SS and J2EE have been removed from J2ME's virtual machine to enable it to run on limited resource machines.

The Java Virtual Machine that comes with J2ME (known as KVM) lacks support for floating point numbers. Another important difference between J2ME applications and J2SE and J2EE applications is the lack of preemptive multitasking. While not a requirement of the Java specification, almost all machines your J2SE and J2EE applications run on support preemptive multitasking. This means that the CPU is shared between multiple Java threads without adding any special code to your programs. This is not the case for many of the devices targeted by J2ME. In order to insure that multi-threading works, you'll have to include calls to Thread.yield() method at any place where your code will tie up the processor -- which is usually inside of loops.

Another tricky part of using the CLDC profile is that the class library lacks many of the classes found in the J2SE class library. You'll have to work within the limitations of this smaller class library while building your application. You can find out which classes are included in the CLDC specification by reviewing the documentation you get when you download the software. The final tricky area you'll have to deal with is the lack access to UI elements -- buttons, menus, graphics, from within the CLDC class library. Since it's next to impossible to develop an application for a Palm OS device without using the Palm's UI, Sun had addressed this problem with the inclusion of a separate class library, com.sun.kjava, which gives you access to the underlying Palm user interface. The following sample program relies on this library to create windows, buttons, and dialog boxes. Be warned that the kjava class library is not an official part of either the MIDP configuration or CLDC profile, and it is likely to change or disappear in a future release. This means that any programs you write that rely on the kjava class library will have to be modified to work with future versions of J2ME. But, right now, it is your only option for accessing the Palm's user interface from within a Java application.

import lang.*;
import com.sun.kjava.*;

public class HelloWorld extends Spotlet
implements DialogOwner {

private Button quitButton;
private Button aboutButton;

private TextBox welcomeTextBox;

private final String welcomeString = "Hello World sample applications demonstrating the use of J2ME and the com.sun.kjava library to produce a Palm Pilot application in Java.";
private final String aboutTitleString = "About Hello World";
private final String aboutString = "HelloWorld J2ME CLDC Application\n (c) 2001 Daniel A. Tauber\ninfo@tauberkienan.com\nhttp://www.tauberkienan.com";


public HelloWorld() {
register(WANT_SYSTEM_KEYS);

;welcomeTextBox = new TextBox(welcomeString, 10, 10, 140, 130);
aboutButton = new Button("About", 75, 140);
aboutButton.setEnabled(true);
quitButton = new Button("Quit", 125, 140);
quitButton.setEnabled(true);
paint();
}

public void dialogDismissed(String title) {
Graphics.clearScreen();
register(WANT_SYSTEM_KEYS);
paint();
}

public void paint() {
welcomeTextBox.paint();
aboutButton.paint();
quitButton.paint();
}

public void penDown(int x, int y) {
if (aboutButton.pressed(x, y)) {
Dialog aboutDialog = new Dialog(this, aboutTitleString, aboutString, "OK");
aboutDialog.showDialog();
}
if (quitButton.pressed(x, y))
System.exit(0);
}


public static void main(String args[]) {
new HelloWorld();
}
}

Dissecting the HelloWorld Application

The HelloWorld application shows the basic features of a CLDC application for a device running the Palm OS. As you look over the code, you'll see a number of features of building applications using the kjava class library. First, the program extends the com.sun.kjava.spotlet class. With kjava, a spotlet is any class that can get focus, that is, receive events from the system such as pen down. In our case, our HelloWorld application needs to respond to pen clicks on the About and Quit buttons, so it needs get the focus. Your application can contain as many classes derived from spotlet as you need, although only one of them can have the focus at any one time. Applications actually take the focus by calling the register method, which we do at the beginning of the HelloWorld constructor and in the dialogDismissed method.

Also, the HelloWorld class implements the DialogOwner interface. A class that implements the DailogOwner interface is a class that creates a dialog box. Our application creates a dialog box in response to a pen click on the About button. To implement the DialogOwner interface, your class needs to include a dialogDismissed member method. This method is called when a dialog box is closed.

The HelloWorld constructor creates three interface elements on the screen: a text box and two buttons. You'll immediately notice one big difference between kjava and J2SE's AWT: kjava does not have any equivalent to AWT's automatic layouts. You have to hard code the position of each interface element on the screen. In our program, we place the text box between 10, 10 and 140, 130. Our two buttons are place at 75,140 and 125, 140. Hard coding positions does not pose a problem when designing for the current crop of Palm OS devices, which always have the same screen size. But hard coding position would be a major headache if your application needed to support devices with multiple screen sizes.

HelloWorld's penDown method is called whenever the user taps the pen on the device. We delegate the work of determining if the click occurred within the bounds of the buttons by calling each button's pressed method in turn. If a button's pressed method returns a true value, which means that the pen down event happened within the bounds of the button, then the proper action for the button is taken. In the case of the About button, we create the About dialog box by creating a new Dialog object. In the case of the Quit button, we terminate the program.

Finally, the HelloWorld's dialogDismissed method is called when the user dismisses the dialog box which we create in response to a click on the About button. In our application, all that this method does is regain the focus by calling the register method and redraw the screen by calling the paint method.

Compiling

Compiling a CLDC application is a two step process. First you must run them through the standard J2SE compiler, specifying the CLDC class libraries instead of the standard J2SE class libraries. After that, you need to process the resulting class file with the preverify program to turn it into a Java application ready for the KVM.

The above sample program is compiled with the command line

javac -g:none -classpath %cldc_classpath% -d %temp% HelloWorld.java
preverify -classpath %cldc_classpath% -s %temp% -d .

Once it is compiled, you can run the program on your desktop machine using

kvm -classpath %cldc_classpath% HelloWorld

Now that you have a CLDC application that will run on your computer, it's time to turn it into a Palm executable.

Running it on a Palm

In order to turn a .class file developed with CLDC into a file that can actually run on a Palm OS device, you'll need to use a number of programs that are included in the j2me_cldc-1_0-src-palm_overlay.zip file. First, you have to turn your .class file into a Palm OS application. All Palm OS application have the extension .prc. You turn your .class file into a .prc file by using the palm.database.MakePalmApp class. Run this on your HelloWorld.class file with the command line

java palm.database.MakePalmApp -bootclasspath %cldc_classpath% HelloWorld

You'll now have the file HelloWorld.prc in the same directory as HelloWorld.class. This file is the Palm application. You can now use the Palm Installer software that comes with your Palm OS device to install this file. In addition to having the .prc version of your application installed on your Palm OS device, you'll also have to have kvm.prc installed. kvm.prc is an implementation of the K Virtual Machine (remember, that is the version of the Java Virtual Machine specified in the MIDL profile) for Palm OS devices.

Resources

A number of resources are available online to continue your investigation of using J2ME to build Java applications for small devices. These sites include

Daniel A. Tauber is a technical strategist and solutions architect, has led the technical development of websites and desktop applications for Fortune 500 companies and the publishing industry.


Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.