Installing and Configuring Tomcat on iSeries

by David Morris

A Bit of History

Tomcat was originally donated to the Apache Software Foundation by Sun Microsystems. Using the donated source as a base, the Apache Software Foundation improved Tomcat by adding new features and incorporating the best parts of JServ, the Apache Software Foundation's previous servlet engine. The culmination of that work is Tomcat 3.3, which supports the Servlet 2.2 and JSP 1.1 specifications. During that time, work began on an entirely new version of Tomcat that supports the latest Servlet 2.3 and JSP 1.2 specifications. The result of that work was last October's release of Tomcat 4.0.1.

Stand Alone or Become a Member of the Tribe?

One of the first decisions you have to make when you decide to start using Tomcat is whether to run Tomcat in conjunction with the Apache HTTP Server or as a stand-alone server. If you have a lot of static HTML pages and only a few servlets, you will want to run Tomcat and the Apache HTTP Server together. If, however, you are building a Web site that uses servlets and JSPs to provide the majority of your content, running Tomcat as a stand-alone server is a viable option.

If you decide to run Tomcat in conjunction with the Apache HTTP Server, you also have to decide whether to run Tomcat in- or out-of-process. When running Tomcat in process, the Apache HTTP Server starts Tomcat as threads within the Apache HTTP Server job. When you run Tomcat out of process, Tomcat is a separate job that can even be on a different computer than the Apache HTTP Server, which communicates with the Apache HTTP Server via sockets.

It is easier to configure Tomcat to run as an in-process server. And an in-process Tomcat server gives better performance and can share authentication provided by the Apache HTTP Server.

Running Tomcat as a stand-alone server is another option to consider if you need the latest servlet support or if the majority of your site uses servlets or JSPs. The version of Tomcat included with the Apache HTTP Server does not support running Tomcat as a stand-alone server; if you choose this option, you have to download and install Tomcat directly from the Jakarta Project's Tomcat Web site.

Getting Started

The easiest way to understand how to deploy applications with Tomcat is to look at an example. Fortunately, Tomcat provides quite a few examples. If you use the Apache HTTP Server with Tomcat, most of the configuration details are handled by the configuration and administration forms supplied by IBM. With the stand-alone version, however, you have to handle those details yourself.

If you use the configuration and administration forms, select the option to install the sample applications when you run the Basic ASF Tomcat wizard. Review the samples. If you chose the default names, they will be in the www/servername/webapps directory, where servername is the name you assigned to the Apache HTTP Server. One thing to be aware of with IBM's configuration wizard is that it does not clean up unused applications. It also creates backup configuration files that it doesn't remove.

With the stand-alone version of Tomcat, the main areas to look at are the server.xml and web.xml files. You will find server.xml in the configuration directory (/jakarta-tomcat-4.0.1/conf). The web.xml files are in the WEB-INF directory for each context that Tomcat serves.

For a stand-alone Tomcat server, the server.xml file defines the ports Tomcat uses. The server.xml file also defines the contexts (directories) that Tomcat serves with Context elements. The path attribute maps part of the URL to the context entry. The docBase attribute identifies the directory containing the files served:

<Context path="" docBase="ROOT" debug="0"/>

The path attribute identifies the part of the URL that comes between the host and the file name. If you use the default installation procedures I describe below for a stand-alone Tomcat server, this Context definition tells Tomcat to map unqualified URL requests to the /jakarta-tomcat-4.0.1/webapps/ROOT directory.

Each context served by Tomcat contains a web.xml file. The main purpose of the web.xml file is to identify the servlets associated with a context. The Tomcat documentation provides an example file (/jakarta- tomcat-4.0.1/webapps/tomcat-docs/appdev/web.xml.txt) that describes how this file is used.

Deploying an Application

Servlets are a natural fit for iSeries applications because servlet-based applications are so similar to 5250 (green-screen) applications. Both servlets and 5250 rely on the iSeries server to do most of the work. The client does very little work and relies on the server for everything except minor formatting and validation.

If you start from scratch, servlet and JSP applications require a lot of low-level programming to store information about sessions and requests, to pass information from Web browsers, and to manage the flow of applications. One way to simplify your applications and avoid a lot of this low-level programming is to use a prebuilt framework, like Struts. The Struts framework uses a Model-View-Controller approach, which simplifies servlet and JSP applications in much the same way that DDS and externally described display files simplify green-screen applications.

Like Tomcat, Struts is part of the Apache Group's Jakarta project. More information on Struts is available on the Struts project page. With Struts development, you use JSPs to define the view of your applications. Java Beans that support your application and interact with the database provide the model. The Struts Action Servlet, which you extend, provides the controller.

You do not have to use Struts with Tomcat, but it is a natural fit, particularly for programmers familiar with externally defined display files and ILE. One way to understand Struts is to install and run some of the Struts examples.

The first step is to download and extract the latest binary release of Struts from the Struts release page. (The current version is 1.0.2, which was released this week.)

If you are running Tomcat as a stand-alone server, copy the struts-example.war file to the webapps directory. That would be /jakarta-tomcat-4.0.1/webapps if you used the default installation directory. If you use IBM's configuration and administration forms, select the option to install a Web Archive, or WAR, file when you run the Basic ASF Tomcat wizard.

Once you have the WAR file in place, stop Tomcat if it is running and then restart it again. Once it has restarted, type in the URL for the struts example as http://host:port/struts-example. This will bring up the Struts walking-tour application. Follow the tour of Struts to gain a better understanding of Struts.

Installing Tomcat Along With the Apache HTTP Server

There are two ways to obtain Tomcat. The first way, which is only available for systems running V4R5 or V5R1, is to order a Group PTF that includes Tomcat. The second way is to simply download Tomcat from the Apache Software Foundation's Tomcat Web site. No matter which version of Tomcat you decide to run, you will get the best results if you use JDK 1.3 (see post-release JDKs), have Qshell installed, and install the latest cumulative and Java Group PTF.

The Group PTF that contains Tomcat depends on your release. For V5R1 systems, order SF99156, and while you are at it, also order SF99069 (Java), SF99097 (Hipers), SF99501 (Database), and SF99450 (CUM). For V4R5 systems, order SF99035 and SF99036, as well as SF99068 (Java), SF99096 (Hipers), SF99105 (Database), and SF99450 (CUM).

After you have installed the PTFs, start the administration instance of the Apache HTTP Server. Use the TCP/IP servers panel in Operations Navigator, or use the Start TCP Server (STRTCPSVR) and End TCP Server (ENDTCPSVR) commands from a green screen:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

Once you have the administration server started, you can use IBM's configuration and administration forms to create or modify an instance of the Apache HTTP Server to run Tomcat or to set up an out-of-process Tomcat server. Incidentally, Tomcat serves these administration pages. Open a browser and type in the following URL, replacing host name with the IP number or host name of your iSeries system:

http://hostname:2001/HTTPAdmin

For an in-process Tomcat server, the first step is to create an instance of the Apache HTTP Server. Select the Administration option and click on Create HTTP Server. Follow the prompts to create an HTTP Server (powered by Apache). When you get to the prompt that asks for a port number, make sure that you specify a port that is not already in use.

After creating the new server, click on the Configuration option and run the Basic ASF Tomcat wizard. This wizard will guide you through the initial setup of an in-process Tomcat server. This wizard also allows you to configure Tomcat to run a sample servlet and JSP. If you accepted the wizard's suggestions and chose to install the samples, you are now ready to try out Tomcat.

To run Tomcat as part of the Apache HTTP Server, start the instance of the HTTP server you just created. Select Administration from the options along the top of your screen and then select Manage HTTP Servers. Select the server you just created and click on the Start button.

You can get more information on configuring Tomcat from the Tomcat configuration page on the IBM iSeries Information Center. There you will find detailed information that describes how to use the configuration support supplied by IBM's configuration and administration forms.

Installing Tomcat as a Stand-Alone Server

To run Tomcat as a stand-alone server, you have to download Tomcat from the Jakarta Tomcat download Web site. I would download the latest stable release build, which is Tomcat 4.0.1.

After downloading the Tomcat Zip file, send it to your iSeries using FTP. Here's how:

1. From the Start menu on your PC, select Run and type FTP yoursystem, replacing your system with the IP number or host name of your iSeries system.

2. Replace c:\temp with the location of the Zip file on your workstation and /tmp with the target directory on your iSeries by typing and entering the following commands:

 bin
quote site namefmt 1
put c:\temp\jakarta-tomcat-4.0.1.zip /tmp/jakarta-                           
tomcat-4.0.1.zip

Once you have the Zip file on your iSeries, start a Qshell session, using the command QSH. Change to the OS/400 Integrated File System (OS/400 IFS) root and extract the Zip file, using the following commands:

cd /
jar –xf /tmp/jakarta-tomcat-4.0.1.zip

Wait for the dollar sign ($) to appear, which indicates that the command is complete. You will then have a directory called jakarta-tomcat-4.0.1, containing the entire Tomcat installation. To rename this directory, use the move (mv) command, as in the following example:

mv jakarta-tomcat-4.0.1 newdirectoryname

Another way to create a stand-alone installation of Tomcat is to install Tomcat on your PC and then copy the PC installation to your iSeries using a mapped drive. This technique has two advantages. The first is that you can follow the installation instructions on the Jakarta Tomcat Web site. Second, you end up with a test installation of Tomcat. (For detailed instructions on how to install Tomcat on your PC, check out Richard Shaler's article "JavaServer Pages 101.")

Now that you have Tomcat on your system, you should compile and optimize all of the JAR files packaged with Tomcat. This takes a while (3 hours on my low-end Model 270) and will occupy three slots in the subsystem. I use the following command:

SBMJOB CMD(QSH CMD('for jar in $(find /jakarta-tomcat-4.0.1/ -name 
''*.jar''); do system "CRTJVAPGM CLSF(''"$jar"'') OPTIMIZE(40)";done')) 
JOB(COMPILE) JOBQ(QPGMR)

Startup/Shutdown Scripts for Stand-Alone Tomcat Server

The next step when creating a stand-alone Tomcat installation is to supply startup and shutdown scripts. I use a basic startup script that sets several environment variables and starts Tomcat. The comments in the startup script describe how to set the environment variable CATALINA_BASE and modify the configuration file server.xml to run multiple stand-alone instances of Tomcat on a single iSeries system. The shutdown script I use is similar and stops Tomcat from running. You copy these scripts to the bin directory where you installed Tomcat.

Adding Servlets and JSPs

The last steps you need to complete for a stand-alone Tomcat server are to add your applications (servlets and JSPs) and start Tomcat. There are a couple of ways to add your applications. First, you can simply place a WAR file into Tomcat's webapps directory. A WAR file is a self-contained Zip file containing a set of files that define an application. Alternatively, you can place a servlet class file or JSP into a context served by Tomcat. You use the web.xml file, found in the web-inf directory of a context, to identify your servlets.

Starting the Stand-Alone Tomcat Server

Finally, you need to start your stand-alone Tomcat server. Start a Qshell session by using the QSH command. After starting Qshell, run the Tomcat startup shell script by entering the following:

/jakarta-tomcat-4.0.1/bin/catalina400.sh

Next, go to a browser and type in the URL http://hostname:8080, replacing host name with the IP number of host name of your iSeries system. That should bring up the Tomcat example page. When you finish browsing those pages, go to another job and end Tomcat by running the shell script:

/jakarta-tomcat-4.0.1/bin/endcatalina400.sh

For this article, I had you run the Tomcat server in an interactive session so you could develop a better understanding of how Tomcat works. You should actually submit the QSH commands that start and stop Tomcat using the Submit Job (SBMJOB) command, as in this example:

SBMJOB CMD(QSH CMD('/jakarta-tomcat-4.0.1/bin/catalina400.sh')) 
JOB(CATALI
NA) JOBQ(QSYSNOMAX) CPYENVVAR(*YES) ALWMLTTHD(*YES)

Catalina Is Waiting for Me

Tomcat 4.0 uses a new servlet container called Catalina that supports the Servlet 2.3 and JSP 1.2 specifications. Those specifications describe several new features, including filters. Filters allow you to modify requests passed to a servlet and to modify the responses returned from a servlet. This is a very powerful capability and makes it a lot easier to apply common processing to servlets.

Filters are likely to become a standard way to secure a site, to measure usage, to monitor response times, to transform output to different formats, and to compress servlet data streams. Filters are also easy to implement and are similar to servlets themselves. To add a new filter, you implement the javax.servlet.Filter class and provide the init, destroy, and doFilter methods.

Like Servlets, you define filters in the web.xml file.

Don't Be a Scaredy-Cat

IBM's HTTP Server-compatibility Web site lists compatibility issues related to running Tomcat on the iSeries. The list states in bold letters that the following features are "not available":