J2ME Enterprise Development

Imtiyaz Haque, Brian O'Connor

ISBN: 978-0-7645-4900-7

Paperback

384 pages

April 2002

J2ME Enterprise Development (0764549006) cover image

This title is out-of-print and not currently available for purchase from this site.

< >

Bonus Content

This companion Web site offers you the opportunity to download the code used in Chapter 5, "Programming with MIDP," or to download the MSales sample application, from which most of the remaining code in the book is pulled.

The following sections tell you more about the MSales application and explain how to download the files and get it up and running.

About the MSales Sample Application

The MSales application is the centerpiece of Part II in this book. It's used to illustrate the APIs covered earlier in the book from the context of a real-world application. The MSales application

Is designed for Palm OS MIDP devices but also runs on MIDP phones
Displays a sales agent's schedule, the products, customers, and complete orders
Uses HTTP to get data from the remote server and upload new order information
Uses a JDBC accessible DB (MS Access) and servlet on the server side to store and retrieve information
Allows user to create new orders that get sent back to the server during syncs
Authenticates users over the Net

Known Bugs

To date, the following program bugs have been detected:

The current schema for the database may be different from what's published in the book. The source code for MSales also has been updated since the book went to press, but the changes are generally minimal.
You can see the previous user's information when logging out and then logging in as another user. Press the Sync Data button to reset the user information on the device.
Some users of the application have noticed problems with dates being off by several hours. This is probably related to how dates are converted in the database.
New orders can consist of only one product. This restriction may be lifted in an updated version.
More bugs will be listed on this site as they are uncovered.

MSales Download File

The J2ME_MSales.zip file contains the source code and binary distribution of the latest MSales code. Inside you will find the following directories contained in a root MSales directory:

bin: Includes ready-to-go .jad and .jar files that you can use without recompiling
classes: Includes precompiled classes for all the MSales objects
server: Includes the MSales servlet source code and the database (in MS Access format) used to set up the MSales server
src: Includes all the source code for the MSales MIDlet
verified: Includes precompiled, preverified classes for all the MSales objects
ReadMe.html: A ReadMe file that includes the information presented here

Unzip this file to wherever you want; for example, unzip it to your C:\ drive.

Setting up the MSales Client and Server

Overview: The process for installing a working copy of MSales on your computer includes many steps, but it's actually quite easy to do. We developed MSales on desktops running Windows 2000, but you can modify the process below for other platforms. The only component tied to Windows is the Access database for the MSales server. The reason we chose Access was that many people using Microsoft Office already have it installed. Given the platform-agnostic nature of any Java application, you may want to move your development to a cross-platform database such as MySQL. Instructions on using alternative databases will be posted separately to this Web site, and alternative options to other components will be mentioned throughout the following guide.

The MSale's setup can be divided into three phases. First, I go through all the software you need to install on your development machine in order to run MSales. Next, I show you how to run the precompiled version of MSales included in this download. Finally, you recompile and repackage MSales from the source code. All three phases are described in the following sections.

Step 1: Software Installation

MSales uses several tools for both the server and client applications, most of which are freely available. Here's the complete list of what you'll need as a minimum (and some sources for alternatives):

Download	Purpose	Location
J2SE 1.3.1	The Standard Edition of Java; you may also download the most recent J2SE 1.4 release (this book uses the Java Debugger included with J2SE 1.4 SDK).	http://java.sun.com/j2se/ 1.3/
Tomcat	The Servlet engine that runs the MSales server component. This install includes the necessary libraries to build servlets. Alternatively, you can download the latest J2EE developer's kit (or another servlet engine), but I don't cover that here.	http://jakarta.apache.org/ tomcat/index.html
MS Access (or another database such as MySQL)	We used MS Access as the backend database for the MSales server. You can also use another database, such as My SQL, although the binary database file included in the download is in Access format.	http://www.microsoft.com/ or http://www.mysql.com/
Forte for Java Community Edition(optional)	Forte provides a nice IDE for creating, testing, and running MIDlets such as MSales. If you install Forte, be sure to do so before installing the Wireless Toolkit. You can then install the "integrated" version of the Toolkit, which adds MIDP functionality to the IDE. Alternatively, you can use your favorite IDE or text editor. Forte simplifies the process of creating MIDlets and provides detailed documentation. For that reason I don't cover its use and configuration in this document.	http://www.sun.com/forte/ ffj/
The J2ME Wireless Toolkit	Provides the tools, such as the emulator and preverifyer, needed to build MIDP applications.	http://java.sun.com/ products/j2mewtoolkit/
Palm OS Emulator and ROM images(optional)	Used in conjunction with the Wireless Toolkit to run MIDP applications, such as MSales, on a Palm OS emulator. We chose to develop MSales for the Palm, but you can also use the phone emulator provided in the toolkit if you like. If you do use the Palm OS Emulator, be sure that you obtain a ROM image from the Palm developers program. This process involves a registration and an easy application. Configuring the Palm OS Emulator is described in great detail in Appendix A of the book.	http://www.palmos.com/ dev/tools/

Install this software in the order given above. Forte is optional, and MS Access as the backend database can be substituted with My SQL, if you prefer. You can use any other third-party servlet container in place of Tomcat, including the J2EE reference implementation available from Sun. After you install all this software, you're ready to move on to the next step.

Tip: A tag like <something_install_dir> refers to the directory in which you installed that tool. Replace it with the actual location.

Step 2: Configure Tools

The next step is to verify that the components you just installed are working correctly. At this time, it's probably a good idea to make sure that your environmental variables are set correctly. Setting the PATH variable allows you to compile and execute the emulator from your current working directory. Tomcat uses the other variables.

Tip: To set these variables in Windows 2000, right-click the My Computer icon and choose Properties. Then choose the Advanced tab and click the Environmental Variables button. You can then choose to add or modify the environmental variables (which are in caps such as PATH). On a UNIX machine, modify these variables in your shell script (such as the .cshrc file) in your home directory. Remember that UNIX (Linux) and Windows machines use slashes differently (/ and \ respectively).

You need to set the variables shown in the following table.

Variable	Value	Reason
CATALINA_HOME	<Tomcat_Install_Dir>	Used by Tomcat to locate its install directory
JAVA_HOME	<J2SE_Install_Dir>	Used by Tomcat to locate the Java home directory
PATH	<J2SE_Install_Dir>\bin; <Tomcat_Install_Dir>\bin; <Toolkit_Install_Dir>\bin;	J2SE commands Tomcat executables Toolkit executables

Step 3: Set Up the MSales Server

This step assumes that you're installing MSales Server on the same machine on which you're running the emulator. The server installation begins by verifying that Tomcat is installed properly.

Check Tomcat

Open a shell window/command prompt.
Type catalina start to start Tomcat.
Open your Web browser and type http://localhost:8080/. You should see the documentation site for Tomcat. If this doesn't work, consult the Tomcat site for troubleshooting the installation.
Type catalina stop in the shell window/command prompt to shut down the server.

Install the Server Files

The following steps put the server files in the correct place:

Extract the J2ME_MSales.zip files to a location on your computer. For example, I extracted it to C:\. You should see a new folder called MSales.
The MSales folder contains a folder called server. This folder contains several files: the MSalesDB.mdb MS Access file, a web.xml Tomcat setting file, and the MSalesServlet.java and Utilities.java files.
The MSales folder also contains a precompiled MSalesServlet.class and a Utilities.class file under the server folder.
Create a new folder in the <Tomcat_Install_Dir>\webapps folder called MSales. Create a subfolder in this folder called WEB-INF. Create another subfolder in WEB-INF called classes. This folder structure is the standard organization for servlets as defined in the servlet spec.
Move the web.xml file to the WEB-INF directory.
Move the MSalesServlet.class and Utilities.class files to the classes folder you just created.
Set up the database. For Windows 2000, choose Start → Settings → Control Panels → Administrative Tools → Data Sources (ODBC)
Click the System DSN tab.
Click the Add button.
Select the Microsoft Access Driver (*.mdb) option and click Finish.
Type MSalesDB as the Data Source Name.
Click the Select button and navigate to the MSales\server directory; then select the MSalesDB.mdb file.
Press OK. The Database ODBC/JDBC bridge is established and the MSalesServlet will be able to read information from the database.
Start Tomcat as you did in the preceding "Check Tomcat" steps.
Load the following URL:
http://localhost:8080/MSales/MSalesServlet?table=AgentAppointmentSet&id=1
If you see data returned, everything is set up correctly. Otherwise, check the Tomcat setup.

Step 4: Set Up the Emulator

Now that the server is working, the next step is to get the emulator included with the Wireless Toolkit linked to the Palm OS emulator. When we developed MSales, we had PDAs in mind. Alternatively, you can skip this step and just use the emulator cell phone skins included in the Toolkit emulator. However, I think it's more effective to use the Palm OS version. Follow these steps:

Link the emulator to the Palm OS device. Open the Start → Programs → J2ME Wireless Toolkit 1.0.3 → Preferences option. Choose PalmOSEmulator from the tree on the left. In the POSE Location field, type
<PalmOSEmulator_Install_Dir>\Emulator.exe
where <PalmOSEmulator_Install_Dir> is the location where you installed the Palm OS emulator.
Press the OK button to close this window.
Navigate back to the same menu and choose the Default Device Selection icon in the Start menu. Choose PalmOS_Device.
The next time the Wireless Toolkit emulator is started, it will launch in the Palm OS emulator rather than the default cell phone skin. You might also want to configure the Palm OS emulator to use the skin and OS version of your choice. For the best results, use the most up-to-date OS in the Palm emulator. See the Palm OS Emulator's documentation and Appendix A in this book for more details about its configuration.

Step 5: Run the Precompiled MSales

At this point, the MSales Server is working and the Wireless Toolkit emulator has been configured to use the Palm OS emulator. Next, you launch the precompiled version of MSales before trying to build your own. Make sure that Tomcat is running before continuing. You can launch the application in two ways:

You can use the MIDlet launcher included in the Wireless Toolkit under Start → Programs → J2ME Wireless Toolkit 1.0.3 → Run MIDP Application. You then choose the <MSales_Install_Dir>\bin\MSales.jad file, which includes information on launching the MSales MIDlet.

You can use the command-line utility to launch the emulator, which is the approach we use in the book. To do this, open a command line and change to the <MSales_Install_Dir>\bin directory. Now type emulator -Xdescriptor MSales.jad

If everything is configured properly, the Palm OS emulator should launch and the MSales application will automatically display. You can then explore the application. Log in using username=JSmith and password=password. Then select Sync Data on the main menu to download data from the server.

Step 6: Building MSales

In the previous sections, we used the precompiled files (.jar and .jad) to launch the MSales application. The following steps help you recompile the MSales client and server from the source files in the <MSales_Install_Dir>\src directory:

Open a command line and change directories to the <MSales_Install_Dir>\src> directory.
Issue the command
javac -d <MSales_Install_Dir>\
classes -bootclasspath <Toolkit_Install_Dir>\
lib\midpapi.zip *.java
where the <Toolkit_Install_Dir> is the directory in which the Wireless Toolkit is installed. This command compiles the source into .class files and places the output into the classes directory.
Preverify the client files. Change the directory to
<MSales_Install_Dir>\classes and then type
preverify -classpath <Toolkit_Install_Dir>\
lib\midpapi.zip;<MSales_Install_Dir>\
classes -d <MSales_Install_Dir>\
verified <MSales_ Install_Dir>\classes
The verified classes are output to the verified directory.
Compile the server code. Change to the <MSales_Install_Dir>\server directory and issue the following command:
javac -bootclasspath <Tomcat_Install_Dir>\
common\lib\servlet.jar;<J2SE_Install_Dir>\
jre\lib\rt.jar *.java
This compiles the MSales servlet and utility class.
The .java files should now be freshly compiled with the client class in the <MSales_Install_Dir>\classes and <MSales_Install_Dir>\verified folders, and the server class in the <MSales_Install_Dir>\server. In Step 7, I show you how to package these.

Tip: It might be easier to use an IDE such as Forte to compile and preverify. The advantage of the command-line utilities is their ability to be automated using the make command, for example.

Step 7: Package MSales

In Step 6, you compiled the client (and server) source code. In order to run the MSales MIDlet, however, you must put the client code in a .jar file with a .jad file description. The following steps walk you through the packaging required to complete the application:

It isn't necessary to package the MSales server components. Copy the updated files to the locations discussed previously and restart the Tomcat server.
You do need to bundle the MSales client class files into a .jar file and an accompanying .jad file. To do this, change directories to the <MSales_Install_Dir>\verified folder and issue this command:
jar cfm <MSales_Install_Dir>\bin\
MSales.jar <MSales_Install_Dir>\
bin\MANIFEST.MF <MSales_Install_Dir>\
verified\*.class

You should now have a finished, updated MSales.jar file in the bin directory that you can load and run by following the previous instructions.