Download jad jbuilder

1. Wireless Development Tutorial Part I
by Jonathan Knudsen and Dana Nourie
September 2003
Download:
HelloMIDlet.java
This article contains everything you need to know to get started developing in the Java 2
Platform, Micro Edition (J2ME) environment. You'll learn how to install the development
tools, how to write your first J2ME 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 J2ME 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.
1.1. What You Need
You have lots of choices for a MIDP development environment. Many Integrated
Development Environments (IDEs) support MIDP development, including Code Warrior
Wireless Studio, Borland's JBuilder.
Sun One Studio, Mobile Edition has its own tutorial that will get you started, and more
documentation is available here.
In this article you'll use Sun's J2ME Wireless Toolkit, which is both free and lightweight. The
J2ME 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 widely available for Windows, Linux, OS X, and Solaris. In this
article, you'll assemble a development environment based on three pieces of software:
ƒ
Java 2 Standard Edition (J2SE) SDK version 1.3 or higher.
ƒ
J2ME 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.
(The J2ME Wireless Toolkit isn't available for OS X, but you can still do MIDP
development. For more information, read Do-It-Yourself MIDP on Mac OS X.)
What editor you use is, of course, entirely up to you. On Unix-like systems, emacs or vi are
popular choices. Some Windows devlopers 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
OS X. Most IDEs include their own editor.
1.2. Installing the J2SE SDK
You'll need the J2SE SDK 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 SDK.) You can download the current version from
http://java.sun.com/j2se/. The current version is 1.4.2. The J2SE SDK is available for Linux,
Solaris, and Windows.
How does the J2SE SDK help you develop wireless applications? First, it provides the Java
platform upon which the J2ME 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 the J2SE SDK, 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 is installed in a directory like c:\j2sdk1.4.2. 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.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)
C:\>
1.3. Installing the J2ME Wireless Toolkit
The next step is to install the J2ME 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
J2ME
Wireless
Toolkit
from
http://java.sun.com/products/j2mewtoolkit/ . Execute the installation file. The installer tries to
locate your J2SE SDK; if it's having trouble, make sure you are pointing it to the directory
where you installed the J2SE SDK. You will also need to specify whether the toolkit will run
by itself (standalone) or be integrated with an IDE. This article assumes you will be running
the toolkit in standalone mode. The files for the toolkit will go into c:\WTK20 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 the J2ME Wireless Toolkit (Click for a full-size image.)
The J2ME 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, 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 J2ME 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:\WTK20\apps\HelloSuite\src"
Place Application resource files in "C:\WTK20\apps\HelloSuite\res"
Place Application library files in "C:\WTK20\apps\HelloSuite\lib"
The toolkit stores each project in a subdirectory of the appsdirectory. The name of the
subdirectory is the same as the name of the project. Here, the toolkit has created a new
directory, c:\WTK20\apps\HelloSuite. Each project subdirectory has a standard structure:
Project directory structure
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.
When you use KToolbar to build a project, several additional directories are created:
Project directory structure after building
As you can see, the J2ME Wireless Toolkit has created classes, tmpclasses, and tmplib. For
the most part you can ignore these directories; the toolkit uses them internally.
1.4. 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));
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:\WTK20\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.
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 J2ME 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 demos, games,
and photoalbum sample projects.
1.5. 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 J2ME
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 environment. To understand this departure, think of a MIDlet that uses the
java.lang.System class. This class has different APIs in J2SE and MIDP. When the toolkit
compiles your MIDlet class, you want it to use the MIDP java.lang.System, not the J2SE
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 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 J2ME 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.
2. 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.
2.1. Resources
The user guide that comes with the J2ME 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
3. Wireless Development Tutorial Part II
In Part I of this tutorial, you learned how to write a simple Java 2, Micro Edition (J2ME)
application. The application, a MIDlet, was designed for the Mobile Information Device
Profile, one of the J2ME 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.
There are two versions of this article, depending on which platform you wish to use 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.
ƒ
The Java 2, Enterprise Edition (J2EE) Reference Implementation (J2EE RI) server is
a full implementation of the J2EE specification. Like Tomcat, it is not intended to be
a production quality server, but it serves as a good place for developers to learn,
prototype, test, and experiment. Again, you can't beat the price: like Tomcat, the J2EE
RI server is freely downloadable.
There are pros and cons for each server, of course. Tomcat is easier to use for servlet
development. However, its capabilities are limited to servlets and JSPs. By constrast, the
J2EE RI server implements the full spectrum of J2EE technologies, including servlets, JSPs,
EJB, JMS, JNDI, and more.
The article you are reading demonstrates servlet development using Tomcat. Click here for
the J2EE RI version of the article.
3.1. Installing and Running Tomcat
Tomcat is distributed as a ZIP archive, available from the Apache Jakarta project. As of this
writing, the current version is 4.1.27.
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-tomcat-4.1.27\.
Tomcat itself is written in Java. To run Tomcat you'll need to tell it where to find your J2SE
installation. To do this, put the location of your J2SE installation in the JAVA_HOME
environment variable. On my machine, the variable has the value c:\j2sdk1.4.0.
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 (Click for a full size image.)
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.
3.2. 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 J2SE 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.27\common\lib\servlet.jar
C:\>javac HitServlet.java
3.3. 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 servletname 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.
3.4. 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 J2ME 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 J2ME 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 J2ME 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 J2ME 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!
4. 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 and J2EE. 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.