Website - J2ME Enterprise Development

About MSales

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 appliction. MSales:

• is designed for PalmOS MIDP devices but also runs on MIDP phones
• displays an Agent's schedule, the products, customers, and complete orders
• uses HTTP to get data from the remote server and upload new order information
• it uses a JDBC accessible DB (MS Access) and servlet on the server side to store and retrieve info
• allows user to create new order which gets sent back to the server during syncs
• authenticates users over the net

Known Bugs

• The current schema for the database may be different from what's published in the book. The source code for MSales has also been updated since the book was printed. The changes are generally minimal.
• You can see the previous user's information when logging out and then logging in as another user. Hit the "sync data" button to reset the user information on the device.
• Some users of the application have seen some problems with dates being off by several hours. This is probably related to dates converted in the database.
• New orders can only consist of one product. This restriction could be lifted in an updated version.
• More bugs will be listed 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 data base (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 that includes the information presented here

Unzip this file to wherever you want, for example I unzipped it to my C:\ drive.

Setting up the MSales Client and Server

Overview:

The process to install a working copy of MSales on your computer includes many steps but it is actually quite easy to do. We developed MSales on desktops running Windows 2000 but you could 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 the website and alternative options to other components will be mentioned throughout the guide below.

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

Step 1: Software Installation

MSales makes use of 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 (the book used 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 developers kit (or another servlet engine) but I won'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 could 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 won'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, like MSales, on a Palm OS emulator. We chose to develop MSales for the Palm but you could also just use the phone emulator provided in the toolkit if you like. If you do use the Palm OS Emulator make sure 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. Any other third party Servlet container can be used in place of Tomcat including the J2EE reference implementation available from Sun. Once you've installed all this software you're ready to move onto the next step.

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

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 your environmental variables are set up correctly. Setting the PATH variable allows you to compile and execute the emulator from your current working directory. The other variables are used by Tomcat.

Tip: To set these variables in Windows 2000 right-click on the "My Computer" icon and choose "Properties." Then choose the "Advanced" tab and click on 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).

The following variables need to be set:

Variable	Value	Reason
CATALINA_HOME	<Tomcat_Install_Dir>	used by Tomcat to locate it's 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 you're installing MSales Server on the same machine you're running the emulator on. The server installation starts with verifying Tomcat is installed properly.

Check Tomcat

• open a shell window/command prompt
• type "catalina start" to start Tomcat
• open your web browser and enter "http://localhost:8080/" you should see the documentation site for Tomcat. If this doesn't work then consult the Tomcat site for troubleshooting the install
• type "catalina stop" in the shell window/command prompt to shutdown the server.

Install the Server Files

These next steps will 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 has 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 Utilities.class files 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.
• Setup the Database. For Windows 2000, select 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, select the MSalesDB.mdb file.
• Hit 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 "Check Tomcat" step.
• Load the following URL: http://localhost:8080/MSales/MSalesServlet?table=AgentAppointmentSet&id=1. If you see data returned then everything is set up correctly. Otherwise check the Tomcat setup.

Step 4: Setup 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 cellphone "skins" included in the Toolkit emulator but I think it's more effective to use the Palm OS version.

• The first step is to link the emulator to the Palm OS device. First, open the Start->Programs->J2ME Wireless Toolkit 1.0.3->Preferences option. Select "PalmOSEmulator" from the tree on the left. In the "POSE Location" field enter "<PalmOSEmulator_Install_Dir>\Emulator.exe" where <PalmOSEmulator_Install_Dir> is the location where you installed the Palm OS emulator.
• Hit the "OK" button to close this window.
• Next, navigate back to the same menu and choose the "Default Device Selection" icon in the Start menu. Choose "PalmOS_Device".
• 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 best results use the most up-to-date OS in the Palm emulator. See the Palm OS Emulator's documentation and the book's Appendix A 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. The next step is to launch the precompiled version of MSales before trying to build your own. Make sure Tomcat is running before continuing. There are two ways to launch the application:

• First, 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.
• The second option is to use the command line utility to launch the emulator, this is the approach used 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. Use username=JSmith and password=password to login. Then select "Sync Data" on the main menu to download data from the server.

Step 6: Building MSales

In the previous steps we used the precompiled files (.jar and .jad) to launch the MSales application. This step looks at recompiling 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 where the Wireless Toolkit is installed. This will compile the source into .class files and place the output into the classes directory.
• The next step is to pre-verify the client files. To do this change directory to <MSales_Install_Dir>\classes. 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.
• Now compile the server code. Change directories to the <MSales_Install_Dir>\server directory.
• Issue the command "javac -bootclasspath <Tomcat_Install_Dir>\common\lib\servlet.jar;<J2SE_Install_Dir>\jre\lib\rt.jar *.java ", this will compile the MSales servlet and utility class.
• The .java files now should all 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. The next step is to package these.

Tip: It might be easies to use an IDE like 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

The previous step looked at compiling the client (and server) source code. In order to run the MSales MIDlet the client code needs to also be put in a jar file with a jad file description. This section looks at the packaging needed to complete an application.

• You don't need to package the MSales server components. Simply copy the updated files to the locations discussed previously and restart the Tomcat server.
• The MSales client class files, however, do need to be bundled together in a jar and accompanying jad file.
• To do this, change directories to the <MSales_Install_Dir>\verified folder.
• Issue the 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.

Helpful Web Links

Here are some useful websites for J2ME and related technologies.

Technical Sites

- www.microjava.com

- www.javaworld.com

- www.ibm.com/developerworks

- theserverside.com

Third Party Tools

- xml.apache.org

- www.ashnasoft.com

- www.mysql.com

- jakarta.apache.org

Sun Sites

- wireless.java.sun.com

- java.sun.com

- java.sun.com/products/j2mewtoolkit

- java.sun.com/products/midp