sun by linxiaoqin



May 07, 2006

Wireless Development Tutorial Part I

By Jonathan Knudsen and Dana Nourie, January 2006


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.
What You Need

In this article you'll use Sun's Sun Java Wireless Toolkit 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 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.
Installing the Java Platform, Standard Edition (J2SE SDK)

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 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

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)


Installing the Sun Java Wireless Toolkit

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
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:

                                                   Project directory 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/
Create a MIDlet

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));

    public void startApp() {

    public void pauseApp() {}

    public void destroyApp(boolean unconditional) {}

    public void commandAction(Command c, Displayable s) {

Save this code as in the src directory of your project. On my computer, this file is saved in

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

                                             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.
A Quick Look Under the Hood

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.
Just Wait 'til Next Time

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


May 07, 2006

Wireless Development Tutorial Part II

By Jonathan Knudsen, January 2006

In Part I of this tutorial, you learned how to write a simple Java Platform, Micro Edition (Java ME) application. The
application, a MIDlet, was designed for the Mobile Information Device Profile, one of the Java ME specifications. Now
you're going to expand your horizons dramatically. You'll learn how to write and deploy a servlet, and then how to hook up
a MIDlet with the servlet. By the time you finish reading this, you'll have all the tools you need to develop end to end
wireless Java applications.

We are using Tomcat platform for servlet development.

    * Tomcat is the freely available reference implementation of the Java servlet and JavaServer Pages (JSP)
specifications. Although it is not meant to be a production quality server, Tomcat is an excellent platform for developing
and testing servlets.

There are pros and cons for using Tomcat server. Tomcat is easier to use for servlet development. However, its
capabilities are limited to servlets and JSPs.
Installing and Running Tomcat

Tomcat is distributed as a ZIP archive, available from the Apache Jakarta project. For this writing, the version is 4.1.31.

Installation of Tomcat is simple: just unzip the download file. You can put it wherever you want. I unzipped it to a root-level
directory, c:\jakarta-tomacat-4.1.31.

Tomcat itself is written in Java. To run Tomcat you'll need to tell it where to find your J2SE SDK installation. To do this, put
the location of your J2SE SDK installation in the JAVA_HOME environment variable. On my machine, the variable has the
value c:\jdk1.5.0_06.

To set the JAVA_HOME environment variable, go to Control Panel>System>Advanced>Environment Variables

To run Tomcat, open a command window. Change directories to Tomcat's bin directory. Type startup and stand back. A
new window will open up and display copious initialization messages:

                                                Tomcat's initialization messages

You can use a browser to test if Tomcat is really running. Try to open the URL http://localhost:8080/ and see what
happens. If Tomcat is running correctly you'll see a default page from Tomcat with links to some servlet and JSP

To shut down Tomcat, open another command window. Change directories to Tomcat's bin directory and run the
shutdown command.

Starting and stopping Tomcat this way is a little clumsy. I recommend creating Windows shortcuts to run the startup and
shutdown commands.
Writing Servlet Source Code

Writing the source code for your servlet is much like writing any other Java source code: use the text editor of your choice
to create .java source files. In this example, you'll write a very simple servlet called HitServlet. Its source code is shown
below. HitServlet simply counts the number of times it's been invoked and writes back to the client a message containing
the count. (It's not thread-safe, but that doesn't matter here.)

import javax.servlet.http.*;
import javax.servlet.*;

public class HitServlet extends HttpServlet {
  private int mCount;

  public void doGet(HttpServletRequest request,
       HttpServletResponse response)
       throws ServletException, IOException {
    String message = "Hits: " + ++mCount;

    PrintWriter out = response.getWriter();


Later, you're going to build a web application with a very specific directory structure. This directory structure makes it easy
for the server to find the pieces of your application. For now, take it on faith and save the source code in a file under the
Tomcat root directory named webapps/midp/WEB-INF/classes/ (Go ahead and create the midp directory
and its subdirectories now.)
Compiling the Servlet

Compiling servlet code is pretty much the same as for other Java development, except for an important twist. Because the
servlet API is not a core part of the Java SE platform, you'll need to add it to your CLASSPATH before you can compile

The servlet API is contained in common/lib/servlet.jar under the Tomcat root directory. Simply add this file to your
CLASSPATH and you will be able to compile using javac. You can edit the CLASSPATH in the system
properties or do it on the command line, as this Windows example demonstrates:

C:\>set CLASSPATH=\jakarta-tomcat-4.1.31\common\lib\servlet.jar


Deploying the Servlet

To deploy your servlet, you'll first need to understand something about web applications. A web application is a collection
of static content, like HTML and image files, servlets, and other resources that can be made accessible via a web interface.
Tomcat comes with several web applications already installed. Go look in the webapps directory under your Tomcat
installation directory and you'll see a few: examples and webdav, for instance. We're going to create a new web
application and place our servlet inside.

First, let's create the web application. You already created a new diretory inside webapps called midp, where you saved
the servlet source code. Now you'll need to edit one of Tomcat's configuration files to tell Tomcat about the new web
application. Open the conf/server.xml file with a text editor. In this file, web applications are called contexts. Scroll down to
find the Context entry for the examples web application, which begins like this:

<!-- Tomcat Examples Context -->
<Context path="/examples" docBase="examples" debug="0"
          reloadable="true" crossContext="true">

Above or below this lengthy context entry (it's closed by </Context>, many lines down), create a new context entry for your
new web application. It will look similar to the opening tag for the examples context, but you'll change the names to midp
as appopriate and close the tag inline.

<!-- MIDP Context -->
<Context path="/midp" docBase="midp" reloadable="true"/>

Once you're finished adding the context entry, save the file.

What these steps do is map incoming HTTP requests to a web application in a particular directory. Specifically, any
incoming HTTP request that begins with "/midp" (the path) will be handed off to the web application located at
webapps/midp (the docBase). The reloadable attribute helps a lot with debugging; it tells Tomcat to reload automatically
any servlet class you change so you don't have to restart the server.

Now that you've created a web application, fill it up. Web applications have a standard directory structure, mandated by
the servlets specification. We won't get into too much detail here. The essential piece of a web application is a web.xml file
that describes the various parts of the web application. This file lives in a standard location in every web application; it's
always stored as WEB-INF/web.xml

It's time to create a web.xml file for your new application. You want to make the servlet accessible to the outside world.
You know the class name of the servlet, HitServlet, and you'd like to make it available under a path like /hits. Note that the
path for the servlet is relative to the path for the web application, so the full path to the servlet will be
http://localhost:8080/midp/hits. Copy the following text (or download it) and save it as webapps/midp/WEB-INF/web.xml
under the Tomcat root directory:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"



This file tells Tomcat to map the servlet called HitServlet to the path /hits. The servlet-name is internal to web.xml; it links
the servlet element to the servlet-mapping element. The name bob is only a friendly example; you can choose whatever
name you want.

You recall that you had saved your servlet source code in a standard directory underneath WEB-INF called classes. This
is where Tomcat expects to find servlet class files, so when you compiled the source code, the servlet class was stored in
the right place.

Your servlet is now deployed in the new web application you created, but note that you must restart Tomcat to have it
recognize the changes you made in server.xml.

To test your handiwork, go to a browser and navigate to http://localhost:8080/midp/hits. You should see the output of
HitServlet. Reload the page a few times and watch the hit counter increase.

For more information on servlet development, see Java Servlet Technology, part of the J2EE Tutorial.
Hooking Up a MIDlet to the Servlet

This part is fun. Now that you have a development environment that supports both MIDP and servlets, you are going to
hook the two worlds together to create an end to end Java application. MIDlets can connect to the world at large via HTTP,
and the servlet you just wrote is available to the world at large via HTTP, so it's a pretty simple matter to have a MIDlet
connect to the servlet.

Start KToolbar (part of the Sun Java Wireless Toolkit) and open the MIDlet project that you created in Part I of this tutorial.
You're going to create a new MIDlet that connects to your servlet, retrieves its output, and displays it. If you haven't

created a Sun Java Wireless Toolkit project yet, go back to Part I and do it now. The full source code for the MIDlet that
connects to HitServlet is shown below.


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

public class HitMIDlet
      extends MIDlet
      implements CommandListener {
  private Display mDisplay;
  private Form mMainForm;
  private StringItem mMessageItem;
  private Command mExitCommand, mConnectCommand;

  public HitMIDlet() {
      mMainForm = new Form("HitMIDlet");
      mMessageItem = new StringItem(null, "");
      mExitCommand = new Command("Exit", Command.EXIT, 0);
      mConnectCommand = new Command("Connect",
          Command.SCREEN, 0);

  public void startApp() {
      mDisplay = Display.getDisplay(this);

  public void pauseApp() {}

  public void destroyApp(boolean unconditional) {}

  public void commandAction(Command c, Displayable s) {
      if (c == mExitCommand)
      else if (c == mConnectCommand) {
        Form waitForm = new Form("Waiting...");
        Thread t =   new Thread() {

                 public void run() {

    private void connect() {
        HttpConnection hc = null;
        InputStream in = null;
        String url = getAppProperty("HitMIDlet.URL");

        try {
            hc = (HttpConnection);
            in = hc.openInputStream();

            int contentLength = (int)hc.getLength();
            byte[] raw = new byte[contentLength];
            int length =;


            // Show the response to the user.
            String s = new String(raw, 0, length);
        catch (IOException ioe) {

The main screen of HitMIDlet is similar to HelloMIDlet, but it includes two commands, Exit and Connect. Connect sets up
a separate thread and calls the connect() method, which takes care of making a network connection and retrieving the

Copy the code above (or download it) into your editor. Save it as inside the apps/HelloSuite/src directory
underneath the Sun Java Wireless Toolkit root directory.

There are two other things to configure to get HitMIDlet working. First, you need to tell the toolkit about this new MIDlet.

Click on Settings..., then select the MIDlets tab. Click on Add and fill in "HitMIDlet" for both the MIDlet name and class
name. You can leave Icon blank. Click on OK and you should see both HelloMIDlet and HitMIDlet listed.

Next, you need to define a system property that HitMIDlet uses as the URL for its network connection. (This property is
retrieved in the third line of the connect() method.) In the toolkit, click on Settings..., then select the User Defined tab. Click
on the Add button. Fill in the property name as HitMIDlet.URL; the value should be the URL that invokes HitServlet, the
same URL you used in a browser to test the servlet. When you're finished, click on OK to dismiss the project settings

Now, in the Sun Java Wireless Toolkit, click on Build to build the project. Assuming you don't see any error messages, you
are now ready to test the application. Make sure your server is running first. Then click on Run and select HitMIDlet.
Select the Connect command. If everything goes well, HitMIDlet will invoke HitServlet and display the results on the
device emulator screen:


Development Notes

Now that you've created your own web application, you can easily modify and test HitServlet. Just change the source
code and recompile. Next time you invoke the servlet from your browser or from HelloMIDlet, Tomcat will use the new
version of the servlet class. (Remember that reloadable attribute in Tomcat's server.xml file? That's what reloadable

If you want to write additional servlets, you probably will need to make changes to your web application's web.xml file. If so,
you will need to bounce the server (restart it) to have the changes take effect.

This article showed how to round out an end to end Java development environment. Part I demonstrated the setup and
use of a MIDlet development environment, while this part of the tutorial showed how to configure and use a servlet
development environment. You learned how to install and run a server and how to write and deploy a servlet. Then you
hooked up the world of MIDlets to the world of servlets, creating a simple end to end Java solution.

The servlet serves as a jumping-off point to the rest of the world, as it gives you access to the full power of J2SE SDK and
Java EE. This is the path to creating powerful end to end Java applications. MIDP clients are relatively small and simple,
but by talking to servlets they can accomplish great things.


To top