Wireless Development Tutorial Part I

Print-friendly Version

Download: HelloMIDlet.java

This article contains everything you need to know to get started developing in the Java Platform, Micro Edition (Java ME) environment. You'll learn how to install the development tools, how to write your first Java ME application, how to build it, and how to test the application in an emulator. The application you'll build, a MIDlet, runs on implementations of the Mobile Information Device Profile, one of the Java ME specifications. (For a background on wireless Java technology, read Introduction to Wireless.)

Most MIDlets will connect to some type of network service, so Part II of this tutorial describes how to set up a servlet development environment and how to write, compile, and test a servlet. The final step is creating a MIDlet that makes a network connection to the servlet.

In this article you'll use Sun's Sun Java Wireless Toolkit for CLDC which is both free and lightweight. The Sun Java Wireless Toolkit can be integrated into IDEs but it can also run standalone, which is how I'll describe it in this article.

MIDP development tools are available only for Windows environment. In this article, you'll assemble a development environment based on three pieces of software:

• Java Platform, Standard Edition version 1.4.2 or higher. (version 1.5.0 is now available to download)
• Sun Java Wireless Toolkit for CLDC This is a package of tools for building and testing MIDlets.
• Text editor. This can be something as rudimentary as Notepad (on Windows) or something more elaborate like jEdit.

What editor you use is, of course, entirely up to you. On Unix-like systems, emacs or vi are popular choices. Some Windows developers use Notepad, but you'll likely want something a little more sophisticated if you do much development work. jEdit is a very capable editor that runs in a Java 2 runtime and works well on different systems like Windows 2000 and Mac. Most IDEs include their own editor.

You'll need J2SE 5.0  to form the foundation of your development environment. (You will sometimes hear developers refer to this as the JDK, or Java Developer's Kit, but the current name is J2SE 5.0) You can download the current version from http://java.sun.com/j2se/1.5.0/download.jsp The current version is 1.5.0. J2SE 5.0  is available for Linux, Solaris, and Windows.

How does J2SE 5.0  help you develop wireless applications? First, it provides the Java platform upon which the Sun Java Wireless Toolkit runs. Second, it includes a Java compiler and other tools that the toolkit uses to build your projects.

Once you've finished downloading J2SE 5.0 , you'll need to install it. In Windows, run the file you just downloaded. The installer asks you some questions and installs the software. If you accept the defaults, J2SE 5.0 is installed in a directory like c:\jdk1.5.0_06. You should add the bin subdirectory to your path, either in your autoexec.bat file (Windows 95/98) or in the System Properties (Windows NT/2000).

To test your installation, open up a command prompt. Type java -version and see what happens. Here's the output on my computer:

C:\>java -version
java version "1.5.0_06"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)

C:\>

The next step is to install the Sun Java Wireless Toolkit, a set of tools that make it easy to build and test MIDP applications. (You can think of the toolkit as a miniature IDE; it automates several of the tasks related to building MIDP applications.)

Begin by downloading the Sun Java Wireless Toolkit from http://java.sun.com/products/sjwtoolkit/. Execute the installation file. The installer tries to locate your J2SE 5.0  ; if it's having trouble, make sure you are pointing it to the directory where you installed J2SE 5.0  . The files for the toolkit will go into c:\WTK23 unless you specify a different directory, and the installer creates shortcuts for various parts of the toolkit.

To run the toolkit itself, select the KToolbar shortcut. You should see the following screen.

Opening screen of Sun Java Wireless Toolkit

The Sun Java Wireless Toolkit works with projects, where the end result of each project is one MIDlet suite. The toolkit works with one project at a time. You can change properties of the current project, build the project, and run the project in a device emulator. Several example projects come installed with the toolkit; we'll look at these later.

Let's jump right in the water by creating a new project. Click on New Project in the button bar. The toolkit prompts you for a project name and the name of a MIDlet class in the project. Fill in HelloSuite and HelloMIDlet as shown below.

Creating a new project

Once you fill in the project name and first MIDlet name, when click on “Create Project” the toolkit gives you a chance to edit the project settings. Just accept the defaults for now; press OK to finish creating the new project. In the text output pane of the Sun Java Wireless Toolkit, you'll see several helpful messages telling you where to store the project's source files. On my machine, these messages are:

Creating project "HelloSuite"
Place Java source files in "C:\WTK23\apps\HelloSuite\src"
Place Application resource files in "C:\WTK23\apps\HelloSuite\res"
Place Application library files in "C:\WTK23\apps\HelloSuite\lib"

The toolkit stores each project in a subdirectory of the apps directory. The name of the subdirectory is the same as the name of the project. Here, the toolkit has created a new directory, c:\WTK23\apps\HelloSuite. Each project subdirectory has a standard structure:

Deploying a Single Application-Server Cluster

The bin directory contains the compiled MIDlet suite (a .jar file) and the MIDlet suite descriptor (a .jad file). The lib directory is the location for any additional JAR files you would like to include in your project. res is the location for resource files, like images or text files, that should be bundled with your MIDlet suite. Finally, the src directory is the place where your source code should be saved. The standard rules about packages and directories apply; for example, source code for a users.Root class would go in src/users/Root.java.

To get you started with MIDlet development, let's write a simple MIDlet. Once you've chosen a text editor, type, cut and paste, or download the following code:

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

public class HelloMIDlet
    extends MIDlet 
    implements CommandListener {
  private Form mMainForm;
  
  public HelloMIDlet() {
    mMainForm = new Form("HelloMIDlet");
    mMainForm.append(new StringItem(null, "Hello, MIDP!"));
    mMainForm.addCommand(new Command("Exit", Command.EXIT, 0));
    mMainForm.setCommandListener(this);
  }
  
  public void startApp() {
    Display.getDisplay(this).setCurrent(mMainForm);
  }
  
  public void pauseApp() {}
  
  public void destroyApp(boolean unconditional) {}
  
  public void commandAction(Command c, Displayable s) {
    notifyDestroyed();
  }
}

Save this code as HelloMIDlet.java in the src directory of your project. On my computer, this file is saved in c:\WTK23\apps\HelloSuite\src\HelloMIDlet.java.

Next, press the Build button in KToolbar. The toolkit will attempt to compile your project. If there are any compiler errors, you'll see them in the text output area of KToolbar. Fix the errors until the project builds successfully.

When you use KToolbar to build a project, several additional directories are created:

Project directory structure after building

As you can see, the Sun Java Wireless Toolkit has created classes, tmpclasses, and tmplib. For the most part you can ignore these directories; the toolkit uses them internally.

Now you're ready to test your MIDlet suite. Click on the Run button. You should see a mobile phone emulator pop up:

HelloSuite running on the emulator

The emulator is showing a list of MIDlets in the MIDlet suite. This example shows only one MIDlet. Although the name you see here is HelloSuite, the class that will be run is HelloMIDlet. To see where this mapping occurs, go to KToolbar and select Settings.... Then click on the MIDlets tab to see a list of the MIDlets in the project.

Back in the emulator, click on the soft button below Launch to start up the MIDlet. It will display a simple screen like the one below. Click on Exit to leave the MIDlet. Close the emulator window or hit the Escape key to end the emulator session.

HelloMIDlet running on the emulator

The emulator you've just used is the DefaultColorPhone. The Sun Java Wireless Toolkit has other emulators as well. Try running HelloMIDlet on some other devices to see how the user interface adapts. Simply select the emulator you'd like in the combo box in KToolbar, then click on Run again.

Once you've had your fill of playing with HelloMIDlet, you might want to check out some of the other projects that come bundled with the toolkit. Feel free to try out the Demo3D, Games, PushPuzzle, NetworkDemo, and many other sample projects available on the apps directory.

Now that you've had some fun, let's take a step back and talk about what it is that the Sun Java Wireless Toolkit does for you. None of it is too complicated, but the toolkit takes several potentially aggravating steps and condenses them into a single button push.

First, what happens when you press the Build button? The toolkit finds all the .java files in the src directory of your project and compiles them. This is no ordinary compilation, however, because the source files must be compiled in a MIDP environment rather than a J2SE 5.0  environment. To understand this departure, think of a MIDlet that uses the java.lang.System class. This class has different APIs in J2SE 5.0  and MIDP. When the toolkit compiles your MIDlet class, you want it to use the MIDP java.lang.System, not J2SE 5.0 version of the class.

You could make this selection yourself, using the command javac and the -bootclasspath option, but it's much simpler just to let the toolkit worry about it.

Beyond compilation, MIDP classes must be preverified before they can be run on a MIDP device. You may recall that J2SE 5.0 has a bytecode verifier that checks .class files before they are loaded. In the MIDP world, verification is split into two phases. The toolkit performs an initial verification at build time, then the device's runtime system performs a second verification when it loads the classes.

You could perform the first verification yourself using the command line preverify tool, but it's much easier to leave this detail to the toolkit.

Finally, MIDlets are bundled into MIDlet suites for distribution to actual devices. This process entails JARing the MIDlet suite class files and the resource files, and putting some extra information in the JAR manifest. Again, these chores are best left to the Sun Java Wireless Toolkit. To bundle up your MIDlet suite, select Project | Package from the menu. The .jad and .jar files for the MIDlet suite will be generated and placed in the bin directory of the project.

You now understand the rudiments of MIDP development and have the software you need to build your own MIDlet suites. That's pretty spectactular all by itself. But MIDP client programming is only half the picture. With some exceptions, most of the really interesting MIDlets will be those that connect to some network service. In Part II of this article, you'll learn how to install, configure and run a server environment. You'll write a simple Java servlet and modify the MIDlet so that it makes a network connection to the servlet. After that, the world is yours for the taking.

The user guide that comes with the Sun Java Wireless Toolkit contains useful information about the application development cycle, MIDlet attributes, the files in each of the installed directories, and device types and portability. It also includes instruction on configuring the emulator and using the Wireless Toolkit from the command line.

If you're new to MIDP programming, you might also find these articles helpful:

• Introduction to Wireless
• Learning Path: Getting Started With MIDP
• All MIDP articles