ONJava.com    
 Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples


Monitoring Applications with Palm OS & Tomcat

by Derek Ferguson
10/05/2001

In this article, I will teach you a little bit about how Expand Beyond Corp. uses Java and the Palm operating system to build a system that allows our clients to monitor and manage their mission-critical systems from virtually anywhere in the world.

I'll begin by talking about our choice of the Palm Operating System as our client platform, and introduce you to Palm Query Applications. After that, we'll move across the network to the server side, to look at the Java that needs to run on the application server to support the wireless monitoring and management of mission-critical systems. I'll show you how to install and configure Tomcat. Then we'll finish up with an example of how to use a wireless handheld to remotely start an Oracle "listener," a vital part of most mission-critical database applications.

Gentlemen, start your emulators!

At the moment, Expand Beyond's software runs on Palm OS, though we are porting it to other platforms, including PocketPC. Since Palm's operating system still holds nearly three-fourths of the PDA market, it's a good starting platform for any wireless software organization.

To develop a client-side application for Palm OS, you must first have a Palm OS-based device at your disposal for testing purposes. If you want to save yourself the expense of purchasing such a device, you are in luck: Palm distributes a free software emulator in the developer section of its Web site.

Screen shot of emulator.
Figure 1.

You will also need to download the ROMs, which is slightly more involved, since you have to register and wait a couple of business days. Once you have the emulator up and running on your system, it should look like Figure 1.

And now, as I would say to my 15-month old daughter, Elizabeth, "You try!" In this section, we will create the user interface for our listener-starting application and examine it using the Palm OS Emulator (POSE).

All about Web Clipping markup

Modern PalmOS handheld devices connect to the Internet primarily through use of a technology called Web Clipping. Web Clipping can be thought of as traditional Web browsing, with two important differences:

Web Clipping doesn't support client-side scripting or binary content (such as applets), nested tables, or extensive control over fonts.

Web Clipping documents must include certain meta tags to let client devices know these pages are safe for Palm consumption. Code Listing 1 shows the markup that we will use for our client application. For further information about syntax, see the Web Clipping documentation on Palm's Web site.

<html>
<head>
  <title>Start Listener</title>
  <meta name="PalmComputingPlatform" content="true">
  <meta name="PalmLauncherRevision" content="1.0">
</head>
  <body>
  <form method="post" action="http://www.pocketdba.com/starter">
  <input type="hidden" name="command" value="lsnrctl">
  <input type="submit" value="Start the Listener">
  </form>
</body>
</html>

We're going to first save that code as an HTML file, and then save it with other relevant files into a Palm Query Application, or .pqa file. Then we'll install the PQA file onto our device.

To create the PQA file from the code listing above, follow these steps.

Emulator screen shot.
Figure 2.

  1. Download and install the Web Clipping Application Builder tool from the Developer's Tool section of the Palm OS Web site.

  2. Save the code from Listing 1 to a text file named index.html.

  3. Start the WCA Builder tool, open the File menu, and choose Open Index.

  4. Select the index.html file you created in Step 2.

  5. Open the File menu and select Build PQA.

  6. Enter a name for the PQA and click on Build.

At this point, you are ready to start the Palm OS emulator and load your Web Clipping application for examination. If you are on Windows, you may do this by right-clicking in the frame of the emulator and choosing Install Application from the pop-up context menu. Select the PQA file you created in Step 6 above. After a few seconds, the icon for your new application should appear on the display. Click this icon to see the interface, as shown in Figure 2.

What's Mission Critical?

Until now, the average database administrator (DBA) has had a pretty miserable lot in life. When a page comes in reporting a mission-critical problem with their database, they have to find a connected PC to fix the problem -- which often cuts into their personal time. Wireless devices that enable the DBA to fix the problem remotely could save lots of time, and the same is true for professionals in other lines of work.

There are many schools of thought on exactly what constitutes a mission-critical system. And, of course, these schools of thought are generally contradictory and mutually exclusive. I offer two heuristics for determining whether or not systems are truly mission-critical.

• How important is the data?
• How much work is stopped if the data can't be interpreted?

At Expand Beyond Corp., we are primarily concerned with the first of these points. We manufacture a product that safeguards a company's Oracle databases against becoming unavailable due to the unavailability of administrative personnel. By giving database administrators wireless access to these systems, mission-critical databases are protected.

In other cases, corporations have needs that go well beyond the database tier. Large, enterprise-level applications like customer-relationship-management (CRM)- and human resource packages need to stay up to keep a company running. In these cases, the remote user would need to execute commands much more complex than the simple "listener starter" example that we show here. The same technology, however, may be used.

All that JAS

Having seen the interface for our PQA in all its glory, you may now actually want to do something useful with it. Demanding, aren't you?

Fortunately, you are in luck. In this section, we will construct the server-side logic needed to support remote invocation of operating system commands from mobile devices. To do this, we will be downloading and installing a Java Application Server.

There are many Java Application Servers (JAS) out there, and the list grows every month. Some are commercial solutions that carry hefty licensing fees for their use. However, at Expand Beyond, we have fallen in love with the Jakarta/Tomcat JAS and standardized it as the sole-supported JAS for use with our server-side application.

Few applications are as easy to install as Tomcat. If you have already installed a compatible Java Development Kit (JDK) and/or Java Runtime Environment (JRE) on your system, then installing Tomcat typically only requires a few steps:

  1. Downloading,
  2. Unpacking, and
  3. Setting the right environment variables.

Tomcat comes out of the Apache Free Software project, and you can download it for no charge at their Web site.

If you want to get up and running fast, select a binary distribution package; explaining how to compile a source distribution is beyond the scope of this article. When looking through the various binaries, you should try to find the most recent release build, which will represent the most stable code base.

Once it's downloaded, unpack it using WinZip or GZip, whichever tool is right for your operating system.

Before you try Tomcat, you have to set an environment variable to tell it where to find Java on your system. Set JAVA_HOME to point to the bin directory of your JDK or JRE installation. Once you have done this, navigate to the bin directory beneath wherever you unpacked Tomcat. In this directory you will find two start-up scripts: one for Windows, one for Unix. Execute the appropriate one and you should see some text scroll across your display.

Once this has finished, try hitting port 8080 on your local box with a Web browser. If Tomcat is working properly, you should see something similar to Figure 3.

Screen shot.
Figure 3.

You try!

Once Tomcat is up and running, you're ready to write a servlet capable of

  1. Receiving a request from the PQA running on the Palm OS device,
  2. Interpreting it, and
  3. Executing it.

In this section, we will show you how the request is received and interpreted. We'll leave the execution of the request and notification of the client for the next section.

The code for this servlet is shown in Listing 2.

import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class StartListener extends HttpServlet {

  public void doGet(HttpServletRequest request, HttpServletResponse response)
  throws IOException, ServletException
  {
    doPost(request, response);
  }

  public void doPost(HttpServletRequest request, HttpServletResponse res)
  throws IOException, ServletException
  {
      String cmd = request.getParameter("command");
      PrintWriter out = res.getWriter();
      out.println("<html>");
  out.println("<head>");
       out.println("<title>Listener Response</title>");
       out.println("<meta name=\"PalmComputingPlatform\" content=\"true\">");
       out.println("<meta name=\"PalmLauncherRevision\" content=\"1.0\">");
      out.println("</head>");
      out.println("<body>");
      out.println("command = " + cmd);
      out.println("</body>");
      out.println("</html>");
  }
}

To try this code, save it to a text file named StartListener.java and compile it, making sure that the file servlet.jar from Tomcat's lib directory is in your classpath. Once you have a class file, you are ready to install it in the JAS. The easiest way to do this is to make it part of an existing Web application by copying your new class file to: \jakarta-tomcat-3.2.1\webapps\examples\WEB-INF\classes

The first thing to understand about receiving the request from our Palm OS device is that it won't really be coming from the Palm OS device itself. Instead, all Web Clipping devices make use of a proxied architecture like the one shown in Figure 4.

Diagram.

This is important, because it means that you cannot test your Web Clipping applications by pointing them at localhost. The reason for this is that the proxy servers attempting to reference localhost would be pointing back at themselves, rather than your own machine. So in order to receive the request on your own instance of Tomcat, you must change the HTML shown in Listing 1 to reference your own machine (either by DNS or IP) and then recreate and reinstall the PQA.

The proper URL will probably be something like: http://yourIP:8080/examples/servlet/StartListener

Once you have set this and reinstalled, you are ready to retry your Web Clipping application. If everything is set properly, you should see something similar to Figure 5.

Screen shot.
Figure 5.

You try!

When we finished our previous code listing, the PQA's request had been received and interpreted by the Java Application Server. In Listing 3 below, we modify our servlet to start the Oracle listener, then inform the client of our success.

import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class StartListener extends HttpServlet {

  public void doGet(HttpServletRequest request, HttpServletResponse response)
  throws IOException, ServletException
  {
    doPost(request, response);
  }

  public void doPost(HttpServletRequest request, HttpServletResponse res)
  throws IOException, ServletException
  {
      String cmd = request.getParameter("command");
   PrintWriter out = res.getWriter();

      out.println("<html>");
  out.println("<head>");
       out.println("<title>Listener Response</title>");
       out.println("<meta name=\"PalmComputingPlatform\" content=\"true\">");
       out.println("<meta name=\"PalmLauncherRevision\" content=\"1.0\">");
      out.println("</head>");
      out.println("<body>");

      try
      {
       Process proc = Runtime.getRuntime().exec (cmd);
      }
      catch (Exception e)
      {
       out.println("Listener *not* started!");
      }

      out.println("command = " + cmd);
      out.println("</body>");
      out.println("</html>");
  }
}

Overwrite the existing StartListener.java file with the code in the listing above, recompile it, and then re-deploy its class file to your JAS. You are now ready to restart an Oracle listener from a wireless Palm OS client! Simply click your PQA application to start it up, and then click the button labeled "Start the Listener." In a matter of seconds, if you indeed have an Oracle listener in the appropriate path on the same box as Tomcat, you should see a success message.

So close, and yet so far

Palm OS Network ProgrammingPalm OS Network Programming
By Greg Winton
September 2001
0-596-00005-7, Order Number: 0057
400 pages, $39.95

Solving some of the more glaring shortcomings in this approach has been the focus of much proprietary Expand Beyond Corporations' Pocket DBA technology. To begin with, the server's response tells you nothing of the output of the command or its specific status. It merely tells you whether or not the servlet generated an error. Using the streamed output features of the Process class, it should be possible to grab the command output and return it to the client.

On the other hand, this is potentially dangerous, because the command is executing on the servlet's main thread. This means that, in the case of a long running command, the system could become completely frozen and inaccessible to other clients while waiting for the command to finish.

Finally, by running this servlet, you make an easy entry point for any hacker who wants to run random commands on your server. In this particular case, all they could do is restart your Oracle listener. However, with a real product like PocketDBA, virtually any command that the user can imagine can be run in a similar fashion. For this reason, any such servlet should be carefully secured with a password and encryption of data coming and going.

Derek Ferguson is a senior technology evangelist at Expand Beyond Corp. (www.xb.com) as an expert on mission critical wireless Java solutions.


Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.