Wireless Development Tutorial Part II

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

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.*;
                   
import java.io.*;

                   
public class HitServlet  
                  
extends HttpServlet  
                  
{
   
                  
private int mCount;
  
   
                  
public void  
                  
doGet(HttpServletRequest request,
      HttpServletResponse response)
       
                  
throws ServletException, IOException  
                  
{
    String message = "Hits: " + ++mCount;

    response.
                  
setContentType("text/plain");
    response.
                  
setContentLength(message.
                  
length());
    PrintWriter out = response.
                  
getWriter();
    out.
                  
println(message);
   
                  
}
                   
}
                

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/HitServlet.java. (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 servlets.

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 HitServlet.java 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 C:\>javac HitServlet.java

 

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"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  <servlet>
    <servlet-name>bob</servlet-name>
    <servlet-class>HitServlet</servlet-class>
  </servlet>
  
  <servlet-mapping>
    <servlet-name>bob</servlet-name>
    <url-pattern>/hits</url-pattern>
  </servlet-mapping>
</web-app>
                

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 java.io.*;

                   
import javax.microedition.io.*;
                   
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);
    mMainForm.
                  
append(mMessageItem);
    mMainForm.
                  
addCommand(mExitCommand);
    mMainForm.
                  
addCommand(mConnectCommand);
    mMainForm.
                  
setCommandListener(this);
   
                  
}
  
   
                  
public void  
                  
startApp()  
                  
{
    mDisplay = Display.
                  
getDisplay(this);
    mDisplay.
                  
setCurrent(mMainForm);
   
                  
}
  
   
                  
public void  
                  
pauseApp()  
                  
{
                  
}
  
   
                  
public void  
                  
destroyApp(
                  
boolean unconditional)  
                  
{
                  
}
  
   
                  
public void  
                  
commandAction(Command c, Displayable s)  
                  
{
    if (c == mExitCommand)
       
                  
notifyDestroyed();
    else if (c == mConnectCommand)  
                  
{
      Form waitForm =  
                  
new  
                  
Form("Waiting...");
      mDisplay.
                  
setCurrent(waitForm);
      Thread t =   
                  
new Thread()  
                  
{
         
                  
public void  
                  
run()  
                  
{
           
                  
connect();
         
                  
}
       
                  
};
      t.
                  
start();
     
                  
}
   
                  
}
  
   
                  
private void  
                  
connect()  
                  
{
    HttpConnection hc = null;
    InputStream in = null;
    String url =  
                  
getAppProperty("HitMIDlet.URL");
    
     
                  
try  
                  
{
      hc = (HttpConnection)Connector.
                  
open(url);
      in = hc.
                  
openInputStream();

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

      in.
                  
close();
      hc.
                  
close();

       
                  
// Show the response to the user.
      String s =  
                  
new  
                  
String(raw,  
                  
0, length);
      mMessageItem.
                  
setText(s);
     
                  
}
     
                  
catch (IOException ioe)  
                  
{
      mMessageItem.
                  
setText(ioe.
                  
toString());
     
                  
}
    mDisplay.
                  
setCurrent(mMainForm);
   
                  
}
                   
}
                

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

Copy the code above (or download it) into your editor. Save it as HitMIDlet.java 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 window.

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:

Success!

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 means.)

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.

Summary

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.

For more information on end to end Java application design, see the Wireless Blueprints, a white paper and example application built using end to end Java technology.