Java 2ME and MIDP Development

Welcome to the world of MIDlets. A MIDlet is a Java application that conforms to the specifications set out by the Connected, Limited Device Configuration (CLDC) and the Mobile Information Device Profile (MIDP).

As you might guess from the specification names, MIDlets are targeted at mobile devices that provide some level of network connectivity. The devices that will run MIDlets also have several common attributes: limited screen size, memory and processing power. The specifications are designed to address these considerations. Typical devices include cellular phones and pagers.

This article will focus on the installation and configuration of the CLDC and MIDP software. We will also write a simple MIDlet and learn the steps required for previewing the MIDlet in a mobile device emulator.

The CLDC defines a specification for a Java virtual machine and a set of core libraries. The CLDC is essentially a slimmed down version of the Java 2 Standard Edition (J2SE) designed for devices with limited memory and resources.

A configuration (for example, CLDC) is designed to run with what is known as a Profile. The MID Profile is a specification that provides a core set of libraries for writing Java applications targeted for mobile devices. A profile defines the libraries that are used by developers to write applications for a specific device or for range of devices. For example, MIDP defines classes for creating user interfaces (textboxes, forms, etc), handling user input, and communicating over a network with HTTP.

Download the Software

Before you can write a MIDlet, you need to download the required software: the Java Developer's Kit (JDK), Connected, Limited Device Configuration (CLDC) and the Mobile Information Device Profile (MIDP).

• Java Development Kit (JDK) -- version 1.2 or greater
• Connected,
• Limited Device Configuration (CLDC)
Mobile Information Device Profile (MIDP) -- Click on Reference Implementation

You may also choose to download the J2ME specification. This download includes the MIDP API. A great reference once you begin development of MIDlets.

Install the Software

Java Developers Kit
The JDK has default directories for installing the files. If you choose to install to a directory other than the default, you will need to write this down, as we will use this path as we progress through this installation.

If you install JDK version 1.3, and choose the default paths, the JDK will be installed into the directory:

c:\jdk1.3

Are you curious about why you need the JDK? Neither the CLDC nor MIDP include the Java compiler (javac.exe) as part of their respective installation. Obviously, without the ability to compile you Java code, you won't get very far.

Connected, Limited Device Configuration (CLDC)
Extract the zip file that you download onto your hard-drive. I recommend the path c:\j2me. Here is what the directory structure will look if you extract the files to the path c:\j2me:

c:\j2me
       |
       j2me_cldc

Mobile Information Device Profile (MIDP)
Once again, extract the zip file to your hard drive. Use the same directory as above: c:\j2me. You will now have a directory structure that should look similar to this:

c:\j2me
       |
       j2me_cldc
       midp-fcs

Configure the Software

Updating the PATH
The PATH environment variable is used by Windows to locate executable programs. We need to update the PATH to point to the location of the Java compiler, as well as directories for the CLDC and MIDP programs.

Update the PATH for JDK

Windows 2000 or Windows NT

• From the Control Panel choose System
• Click Environment (or Advanced/Environment)
• Find the PATH entry and at the end, add the location of the /bin directory in your JDK install path. Assuming you installed version 1.3 of the JDK, and selected the default installation path, you would add the following to the end of the path:
  

  C:\jdk1.3 

For Windows 98 or Windows 95

Windows includes a program called the System Configuration Editor. This program is a quick and easy way to update configuration files including: win.ini, system.ini, config.sys and autoexec.bat. To start the editor from within Windows:

• Click the Start button
• Select Run
• Enter sysedit in the dialog box
• Click Ok

Find your way to the autoexec.bat dialog box. Assuming you installed version 1.3 of the JDK, and selected the default installation path, enter the following:

If there is not an entry for PATH add this line:

    PATH=C:\jdk1.3\bin

If there is an entry for PATH, find the end of the entry and add:

C:\jdk1.3\bin

Update the PATH for CLDC
You will also need to update your PATH environment variable to point to the directory where the CLDC executable files are located (the K Virtual Machine and class file preverifier).

Follow the same steps as outlined above to add to the PATH: C:\j2me\j2me_cldc\bin

Update the PATH for MIDP
One last time, update your PATH environment to reference the directory where the MIDP executable file is located; this is the cellular phone emulator for testing your MIDlets.

Follow the same steps as outlined above to add to the PATH: C:\j2me\midp-fcs\bin

Update/Insert the CLASSPATH Environment Variable
CLASSPATH tells the Java compiler where to search for classes that are not part of the Java (JDK) platform itself. In our case, we need to update CLASSPATH to refer to the MIDP classes. You will also need to have a reference to the current directory (".") as part of the CLASSPATH.

Follow the same steps as outlined for the PATH, to update the CLASSPATH: CLASSPATH=C:\j2me\midp-fcs\classes;. -- notice the "." at the end to represent the current working directory.

Insert the SCREEN_DEPTH Environment Variable
MIDP includes a mobile device emulator to test your MIDlets. The emulator can run in color or various shades of black and white. To specify the number of colors, you can add the environment variable named SCREEN_DEPTH. For example:

SCREEN_DEPTH=8

You can add this variable to the environment as you did with the PATH and CLASSPATH variable.

Installation Checklist

The PATH should now look something like the following (not including any entries that may already be a part of your path):

PATH=c:\jdk1.3\bin; c:\j2me\j2me_cldc\bin;c:\j2me\midp-fcs\bin;

You can check to see what the PATH variable contains by going to a command (DOS) prompt and entering:

set PATH 

If you look in Windows Explorer, the directory hierarchy should now include:

c:\jdk\1.3\bin

c:\j2me
       |
       j2me_cldc
       |
       midp-fcs

Test Your Installation

Before writing a MIDlet, let's verify that all the software was installed correctly.

1. Go to a command prompt
2. To test the CLDC installation, type in preverify and press enter. You should see a screen that looks similar to the following:
   
3. To test the MIDP installation, type in midp and press enter. You should see a window pop up that looks like the image below:
   
4. To test the JDK installation, type in java -version and press enter. A screen like the following should appear:
   

Troubleshooting

Here are a few things to look for if any of these steps fails:

• Make sure each program is installed correctly. Use Windows Explorer to find the program causing the problem. For example, locate the program midp.exe. For my installation this in the directory: C:\j2me\midp-fcs\bin. Double click the program and it should start. If you cannot locate the file, or it doesn't run, you may need to uninstall and reinstall the application.

  If it runs but fails when called from the command line, you know that something is incorrect in PATH. Remember, the PATH variable tells Windows where to located executable files.

• Verify the directory paths in the PATH environment variable are correct. Once again, using Windows Explorer, locate the directory of the executable as shown above, and look in the "Address" inside Explorer (see below). This is the full directory path to the program. You can copy and paste this directory into the PATH variable.

  

Your First MIDlet

Let's write a very simple MIDlet that will create a textbox with a message. We'll also add a command button to exit the MIDlet.

Writing the Java Source Code
Create a new directory to hold your MIDlet, for example, c:\midlets

Within this directory create directory called firstMIDlet. Using any text editor, create a file called simpleMIDlet.java and type in the Java source code shown below. Save the file in the directory c:\midlets\firstMIDlet (or whatever path you choose). The full path to the MIDlet source file should now be something like c:\midlets\firstMIDlet\simpleMIDlet.java.

simpleMIDlet.java

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

public class simpleMIDlet extends MIDlet implements CommandListener
{
private Display display; // Reference to Display object for this MIDlet
private TextBox tbxMain; // Textbox to display a message
private Command cmdExit; // Button to exit the MIDlet

// MIDlet constructor
public simpleMIDlet()
{
display = Display.getDisplay(this);

cmdExit = new Command("Exit", Command.SCREEN, 1);

tbxMain = new TextBox("Simple MIDlet", "Welcome ", 50, 0);
tbxMain.addCommand(cmdExit);
tbxMain.setCommandListener(this);
}

// Called by application manager to start the MIDlet.
public void startApp()
{
display.setCurrent(tbxMain);
}

// A required method
public void pauseApp()
{ }

// A required method
public void destroyApp(boolean unconditional)
{ }

// Check to see if Exit command was selected
public void commandAction(Command c, Displayable s)
{
if (c == cmdExit)
{
destroyApp(false);
notifyDestroyed();
}
}
}

At this point, don't worry about what each line of code is doing. Focus instead on the development cycle. In a future article we will cover all the code, from top to bottom.

Compile and Preverify
Now you must compile the java source file and preverify the resulting class file.

1. Compile the Source Code

   Go to a command prompt. Change to the project directory where you saved the file. Compile the program by giving a command like

   javac -bootclasspath c:\j2me\midp-fcs\classes simpleMIDlet.java

   The option -bootclasspath c:\j2me\midp-fcs\classes specifies were to locate the Java bootstrap (startup) class files. We must point to the midp classes otherwise the JDK classes will be used.

   The file firstMIDlet.class will be created (by default, in the same directory as the Java source file) after successfully compiling firstMIDlet.java

2. Preverify the class file

   preverify -classpath
   c:\j2me\midp-fcs\classes;. -d . firstMIDlet

   The option -classpath c:\j2me\midp-fcs\classes;. specifies where to locate the class files for preverification. This includes the MIDP classes that are needed as part of the verification process (specified by c:\j2me\midp-fcs\classes) and your class file, which is located in the current directory (specified by ".").

   The option -d . informs the preverifier where to put the verified class files. The "." specifies the current directory, the same location as the original class file.

Note: The preceding preverify command line options will overwrite the original class file with a new, preverified class file. You may want to separate class files into two directories, those created by compiling, and those created by preverifying. Class files that are not preverified cannot be loaded by the application manager.

Run the MIDlet

We are now ready to run the MIDlet inside the mobile device emulator. While still at the command prompt, enter

midp firstMIDlet

You should see the following output.

There it is, your first MIDlet. Once you've been through the development of one MIDlet, the process doesn't change much. I like to put all the steps (compile, preverify, etc.) into a DOS batch file. Then I can run a single program to accomplish all the steps. For example, here is a simple batch (cc.bat) file that I used to create and test this MIDlet.

javac -bootclasspath c:\j2me\midp-fcs\classes firstMIDLet.java 

pause
preverify -classpath c:\j2me\midp-fcs\classes;. -d . firstMIDlet

midp firstMIDlet

The pause command will wait for a keypress before executing the next command. If you have an error in your Java source file, you can press Control-C to exit the batch file, skipping the preverification and launching of the MIDlet.

Summary

With the exception of the software requirements -- installing CLDC and MIDP -- creating a MIDlet is really no different than writing any standard Java application. The CLDC provides a slimmed down version of the J2SE, while MIDP provides specific libraries for developing mobile device applications.

In the next article, we will look into packaging multiple MIDlets using a Java archive file (jar) and Java application descriptor file (jad). We'll also show an example MIDlet that uses Java Packages, and we'll discuss how this affects the jar and jad files. We'll also show you how to upload and preview your MIDlet(s) from a web server.

John W. Muchow is an expert Java Developer and Trainer specializing in J2ME.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.