Developing a Simple Application

This book would not be a true programming book if the “Hello World” example was missing. Actually, we need three different “Hello World” examples to cover the CLDC reference implementation from Sun as well as the MIDP and PDAP CLDC profiles. The following sections describe the steps necessary to compile and run a simple KVM program for each target platform.

Setting Up the System Environment Variables

If you are using one of the integrated development environments, you can probably skip the installation parts of this section. Just type the example and click Build or Compile and then Run, depending on the type of IDE you are using.

For command-line operation, it is helpful to insert the bin/win32 directory located in your J2ME installation into the system search path. For the MIDP SDK, you need to add the build/win32/tools directory to the system path as well. For Windows 95/98, this is performed by adding the corresponding directory to the path command in the file c:autoexec.bat. If you're running Windows NT 4.0 or Windows 2000, open the Properties dialog box by right-clicking on My Computer on your desktop and selecting Properties. The path information is located in the Extended tab.

The kvm and preverify utilities are also available for Solaris and Linux. However, the executables are located in different directories or download packages. Please refer to the corresponding documentation for installation on Unix systems.

Testing the Setup

In order to work with the command-line oriented SDKs, the first step is to open a command line. Windows users just need to click the Start button and choose Programs, followed by MS-DOS Command Line. For Unix, the way a command shell window is opened differs, depending on the Desktop Manager and the exact system setup. For many installations, you just need to click on the shell symbol in the start bar.

Before beginning, it makes sense to perform a short test to see whether the environment is set up correctly. Please do not skip the test: It will probably save you from spending time searching for simple and avoidable problems.

To test whether the preverify command is in the system search path, type in the following command:

						C:> preverify
					

The command should generate the following output (or similar):

Usage: preverify [options] classnames|dirnames ...

where options include:
   -classpath <directories separated by ';'>
                  Directories in which to look for classes
   -d <directory> Directory in which output is written (default is ./output/)
   @<filename>    Read command line arguments from a text file

If you get a “command or file name not found” error message, the PATH environment variable probably is not set correctly. Include the bin directory of the KVM installation in your system search path.

Now perform the same test for the javac command:

						C:> javac
					

Again, if the system returns a “command or file name not found” error message, ensure that a JDK is installed and also that the JDK bin directory is in the system search path, as described in the previous section.

Now that you are sure your system is set up properly, you're ready for real programming. You can go directly to the subsection of the target profile for which you are planning to program, or you can go through all three if you want to get an overview of the profiles.

CLDC KVM Reference Implementation

Begin by setting an environment variable that points to the CLDC and Kjava classes:

Windows:

set CLDC_BCP=c:j2me_cldc in common api classes

Unix/Csh:

setenv CLDC_BCP ~/j2me_cldc/bin/common/api/classes

Unix/Bash:

export CLDC_BCP=~/j2me_cldc/bin/common/api/classes

Note that the actual directory containing the CLDC and Kjava classes depends on the exact installation and version number; it may differ from this example. If so, set the CLDC_BCP variable accordingly.

On Windows 98, you can add the previous line to the file c:autoexec.bat. On Unix systems, add the line to the corresponding startup or login script. The changes will then affect all command lines automatically. If you're running Windows NT 4.0 or Windows 2000 Professional, the system environment variables are set in the same place as the system search path. Open the system properties dialog by right-clicking My Computer on your desktop and selecting Properties. Then, choose the Extended tab and select Environment Variables to set the CLDC_BCP variable permanently. Select New for User Variables to open a dialog box in which you can set the name (for example, CLDC_BCP) and the value (c:j2me_cldcinapiclasses) of the variable. When you click OK, the new variable will be stored permanently and will be available in all new command shells. Shells already started are not affected, so they must be closed and restarted.

Finally, check whether the environment variable pointing to the CLDC and Kjava classes is set properly:

Now that you have made sure the compiling environment is set up properly, you can start with the sample application. Listing 1.1 contains the complete source code of the HelloCldc.java file.

Listing 1.1. Hello Cldc.java—The HelloCldc Sample Source Code

public class HelloCldc {

    public static void main (String [] args) {
        System.out.println("Hello CLDC.");

    System.out.println("This application is running on a "
            + System.getProperty("microedition.configuration")
            + " JVM");
    }
}

You now can compile the sample program using the following command:

The bootclasspath parameter is necessary because the program cannot be compiled with the standard Java desktop libraries; it must access the CLDC and Kjava libraries.

If the compile command line does not produce any error message, you can perform the preverify step:

This step is necessary to include verification hints in the class file, simplifying the class verification on the target device. Future javac versions may have a switch to perform preverification at compilation time, simplifying J2ME application development.

The preverify step creates a new subdirectory named output, where the preverified classes are placed.

If the preverify step is successful, you can test the application with the command line kvm:

						cd output
						kvm HelloCldc
					

These commands change the current directory to the output directory containing the preverified files and start the kvm with the new verified HelloCldc class. The following output will be generated:

Hello CLDC.
This application is running on a CLDC-1.0 JVM

Hello MIDP

Similar to using the CLDC RI, the first step is to set up an environment variable pointing to the MIDP library classes. The environment variable simplifies the following compilation steps and helps avoid annoying problems resulting from typos in long path names:

You can make sure that the system path is set properly by typing MIDP on the command line. If the cell phone emulation appears, and the current directory is not the MIDP bin directory, the system path is set correctly. Please refer to the previous section if the path is not set or if you would like to set the variable(s) permanently.

Again, we will compile a simple “Hello World” program. The corresponding Java program for the MIDP API is contained in Listing 1.2. Programming with the MIDP API is described in Chapter 3, “MIDP Programming.” Here, we will focus on the compilation steps.

Listing 1.2. HelloMidp.java—The Source Code of the MIDP Sample

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

public class HelloMidp extends MIDlet {

    public void startApp() {
        Form form = new Form ("HelloMidp");
        Display.getDisplay (this).setCurrent (form);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
    }
}

Change to the directory containing the Java file and compile the program using this command:

Now, preverify the program:

The preverification command creates a new output directory where it stores the preverified classes. You can test the MIDlet by typing the following commands:

						cd output
						midp HelloMidp
					

These commands change the current directory to the output directory containing the preverified files and start the MIDP emulator with the new verified HelloMidp class, as shown in Figure 1.8.

In order to deploy programs that consist of multiple classes, JAR files from the desktop are used to bundle all necessary application classes together. Fortunately, you can just jar the complete output directory generated by the preverifier—you do not need to specify the filenames again for jar:

jar –cf hellomidp.jar output

After you successfully create the JAR file, you need to create a Java Application Descriptor (JAD) file. The JAD file encapsulates the information about the contents of the JAR file. In contrast to the manifest file, the JAD file is not included in the archive. It is intended to support automatic download of MIDlets. Listing 1.3 shows the JAD file for the HelloMidp example MIDlet.

Listing 1.3. HelloMidp.jad—The JAD File for the HelloMidp MIDlet

MIDlet-Name: HelloMidp
MIDlet-Version: 1.0
MIDlet-Vendor: Michael Kroll & Stefan Haustein
MIDlet-Jar-Size: 908
MIDlet-Jar-URL: hellomidp.jar
MIDlet-1: HelloMidp, , HelloMidp

The first five entries are self-explanatory (the jar size may differ depending on compiler options and jar compression). The last entry, MIDlet-1, determines the first and only MIDlet that is available in the JAR file. By adding similar entries, it is possible to put more than one MIDlet into a single JAD file and its respective JAR file.

The value of the MIDlet-<Number> attribute consists of three parameters:

MIDlet-<Number>: <name>, <icon>, <class>

<Number> is just an enumeration of the MIDlets in the JAR file. Our example contains only a single MIDlet, so there is only a single entry named MIDlet-1. If more MIDlets were stored in the JAR file, the entries would be named MIDlet-2, MIDlet-3, and so on.

The parameter <name> describes the name of the MIDlet that is displayed on the device after the descriptor file is loaded. The <icon> parameter specifies an icon that can be displayed in the list. The last parameter, <class>, specifies the name of the actual subclass of MIDlet implemented by the application.

In order to start the HelloMidp sample application, place the JAD file contained in Listing 1.3 in the same directory as the JAR file. Change to that directory and type the following command:

						midp –descriptor hellomidp.jad
					

When executing this command, the MID emulation will show a selection menu (see Figure 1.9). Select the HelloMidp entry. The screen will show the output of the HelloMidp example (shown in Figure 1.8).

Hello PDAP

Unfortunately, at the time this book was printed, no official PDAP implementation was available. However, we expect the compilation steps to be similar to compiling MIDP programs, except from using a different bootclasspath.

Actually, because PDAP is a complete superset of MIDP, the MIDP example contained in Listing 1.2 is a valid PDAP example as well. However, a “true” PDAP application will take advantage of the more sophisticated AWT-based user interface capabilities of PDAP. In order to sketch the differences, Listing 1.4 contains a PDAP example with the corresponding modifications.

Listing 1.4. HelloPdap.java—The HelloPdap Sample Source Code

import java.awt.*;
import java.awt.event.*;

import javax.microedition.midlet.*;

public class HelloPdap extends MIDlet {

    private Frame frame;

    HelloPdap () {
        frame = new Frame ("HelloPdap");
        frame.pack ();
    }

    public void startApp() {
        frame.show();
    }

    public void pauseApp() {
    }

    public void destroyApp (boolean unconditional) {
        frame.dispose ();
    }
}

Besides the application itself, the JAD files also need a slight modification. Again, any valid MIDP JAD file is also a valid PDAP JAD file. However, for “true” PDAP applications, using the advanced capabilities of the PDA profile, a new entry type PDAlet-<Number> must be used. If a MIDlet-<Number> entry with the same number <Number> is included, the PDAlet entry overrides the corresponding MIDlet entry. This allows you to include both MIDP and PDAP versions of the same application in a single pair of JAD and JAR files. The syntax of the PDAlet entries is identical to the syntax of the MIDlet entries. For our example, a corresponding JAD file including the MIDP version of the sample is shown in Listing 1.5.

Listing 1.5. HelloPdap.jad—The JAD File for the HelloPdap Application, and the HelloMidp MIDlet as a Fallback Option

MIDlet-Name: Hello
MIDlet-Version: 1.0
MIDlet-Vendor: Michael Kroll & Stefan Haustein
MIDlet-Jar-Size: ???
MIDlet-Jar-URL: hello.jar
MIDlet-1: HelloMidp, , HelloMidp
PDAlet-1: HelloPdap, , HelloPdap