Introduction: An alternative to commercial application servers
Ease of integration and simplified installation and configuration are the key characteristics of IBM System i5 products that help customers easily implement on demand business solutions. Apache Software Foundation (ASF) Jakarta Tomcat 3.2.4 (so named because it is a product of the ASF Jakarta Project) is an open source application server, providing run time support for servlets and Java™Server Pages (JSP) technology. It is much easier to configure, deploy, and run Web applications on Tomcat than on most commercially available application servers. More important, Tomcat consumes far less RAM and processor overhead than commercial servers, enabling it to run as a light-weight application server on low-end iSeries™.
Although Tomcat has been widely used by back-end administrators and developers, there are few detailed technical documents provided to satisfy users on all aspects of Tomcat on System i5. In this article, we provide fast configuration instructions and entry-level problem solutions for users who want to implement Web applications using Tomcat on System i5. It can help entry-level users familiarize themselves with Tomcat configuration issues and System i5/OS working mechanisms. It also provides some of the pros and cons of using Tomcat on System i5. This article can also be a reference for testers who are working on System i5 system verification tests.
1. Setting up communication between HTTP server and Tomcat
To work with an HTTP server (such as Apache), ASF Jakarta Tomcat needs an agent that resides in the HTTP server and sends it a servlet request. This agent is the Web server plug-in. It enables communication between the HTTP server and the ASF Tomcat servlet engine. It must be included in the HTTP configuration file with the LoadModule directive. The usage for the directive is LoadModule jk_module/QSYS.LIB/QHTTPSVR.LIB/QZTCJK.SRVPGM.
Two types of Tomcat engines are currently provided with i5/OS, an in-process engine and an out-of-process engine. Using the in-process engine, ASF Jakarta Tomcat and the HTTP server run in the same process and communicate through a Java Native Interface (JNI). Using the out-of-process engine, Tomcat and the HTTP server run in a separate process (even on separate systems) and communicate through Transmission Control Protocol/Internet Protocol (TCP/IP) sockets. The ASF Tomcat server process runs in the QSYSWRK subsystem.
Tomcat runs under its own directory structure. This directory structure is used by the HTTP server, since it is included in the HTTP configuration file. The directory structure can be located in the root or QOpenSys file systems. See Figure 1 and Table 1 for details about the Tomcat directory structure.
Figure1. Tomcat directory structure
Table 1. Tomcat directory structure details
| Directory | Description |
|---|---|
Tomcat_home
| This base directory is for ASF Tomcat. The directory can be located in the root or QOpenSys file systems. For an in-process ASF Tomcat configuration, the default Tomcat_home directory is set to the HTTP server directory (/www/<server_name>/ ). For an out-of-process ASF Tomcat configuration, the default directory is set to ASFTomcat/<tomcat_server_name>/.
Within the Tomcat_home directory, there are subdirectories for logs and configuration information.
|
Tomcat_home/webapps
| This directory contains WAR files if you have them. All WAR files are expanded and subdirectories are added as contexts. |
Tomcat_home/conf
| This directory contains the server.xml and workers.properties configuration files. For an in-process ASF Tomcat configuration, this directory also contains the httpd.conf file for the HTTP server. |
Tomcat_home/work
| This directory is automatically generated by ASF Tomcat as a place to store intermediate files. |
Tomcat_home/logs
| This directory contains all log files. |
Tomcat_home/java
| This directory contains a subdirectory, lib, which provides a place to put .jar and .class files that you want to add to the class path. |
The ASF Jakarta Tomcat directives are used by the HTTP server to redirect the requests of servlets and JSP and WAR files to the servlet engine. Both in-process and out-of-process engines can be configured on the same HTTP server instance. The directive shown in Listing 1, Line 2, must be issued before using any other Tomcat directives. The jk_module module must be loaded first. Directives in Lines 22 through 25 need to be set as HTTP server global configurations, as follows:
JkWorkersFile (Line 22): Use the JkWorkersFile directive to define the name of a file that contains configuration information. That is, it describes how jk_module attaches to the ASF Tomcat servlet engine.
JkLogFile (Line 23): Use the JkLogFile directive to describe the full pathname of the jk_module log file.
JkLogLevel (Line 24): Use the JkLogLevel directive to describe the detail of logging for the log file defined by JkLogFile. The possible values for this directive are the following:
-
debug -
info -
error -
emerg
JkMount (Line 25): The JkMount directive specifies which Uniform Resource Identifier (URI) contexts are sent to a Tomcat worker.
Listing 1. HTTP server configuration files for in-process and out-of-process Tomcat
2.1 In-process and out-of-process implementation
As shown in Listing 1, directives in Line 21 and Line 25 are specific to out-of-process and in-process modules, respectively. The JkMount directive (Line 25) specifies which URI contexts are sent to a Tomcat worker. For an in-process module, the worker's name only can be selected as inprocess/. For an out-of-process module, you can define the worker's name by yourself and select an existing Tomcat instance port number to associate with the worker name.
For more detailed Tomcat in-process and out-of-process configuration instructions, refer to the IBM Redbook, IBM HTTP Server (powered by Apache): An Integrated Solution for IBM eServer™ iSeries Servers.
3.1. Setting the JDK version for a specific Tomcat user
Officially, Tomcat on System i5 only supports JDK 1.2 or 1.3. But right now, most System i5 computers use a higher JDK version (for example, JDK 1.4 or 1.5). Before using Tomcat, you should check your computer's Java version by going to QSH environment and using the Java -version command.
If the JDK version is higher than 1.3 and you get a Java version error when running an application on Tomcat, you need to configure i5 system to force the user to run JDK 1.3 or 1.2 version.
The SystemDefault.properties file is used to control Java behavior on a System i5 computer. This file can control global Java behavior for the entire system when it is placed in the following directory: /QIBM/UserData/Java400/. But we do not recommend changing this file under /QIBM/UserData/Java400/. Just specifying the user-level JDK version (for users who run Web applications on Tomcat) will not influence other users that use higher JDK versions.
To configure for a special user, you should place this file in the user¡¯s root directory, /home/<userid>/. The SystemDefault.properties file that is in user's home directory takes priority over the SystemDefault.properties file that is in the /QIBM/UserData/Java400 directory. Then, add java.version=1.3 in the file under the user's home directory to make certain the user runs JDK 1.3 when he or she logs on to the system.
3.2. Setting an alias for a Web application on Tomcat
For security reasons, most Web applications set an alias, which is used by a public user to replace the real address for accessing the Web site. Tomcat on System i5 provides the mechanism to set an alias. Here is our experience of setting an alias for a Tomcat Web application.
As shown in Figures 2, 3, and 4, you use the following three parameters to set an alias for both in-process and out-of-process modules:
- URLs (mount points). Specifies a URL path that is routed to a particular Tomcat worker. When a URL comes into the HTTP server and it matches the specified URL path, it is handled by the Tomcat servlet engine rather than by the normal HTTP server.
- URL path. Specifies the URL path that is routed to the application context.
- Application base directory. Specifies the directory tree containing the application (relative to the Tomcat home directory). Under normal conditions, this directory should be a subdirectory of Web applications under the Tomcat home directory.
During our testing, we found that URL path is the most important parameter for setting an alias: You can define your application's alias by entering its value, preceded by a forward slash, in the URL path field. The URLs (mount points) value must be the same as URL path value, followed by a forward slash and an asterisk; otherwise, the user might get a Not Found error when attempting to run applications.
Figure 2. In-process Tomcat setting within the HTTP server
For an in-process module, you can configure these three parameters just in the HTTP server administrating page. But for an out-of-process module, you must create the Tomcat server separately from the HTTP server, setting the URL path and Application base directory on the Tomcat server, and setting URLs (mount points) on HTTP server, as shown in Figure 3 and 4.
Figure 3. Out-of-process configuration on Tomcat server
Figure 4. Out-of –process Tomcat setting on HTTP server
3.3. Correct coded character set ID setting for character data conversions
When you run a Java application that needs to access a DB2® database on System i5, conversion issues can result in you getting the javax.servlet.ServletException: Correct coded character set ID (CCSID) value is not valid error. To solve this kind of problem, you need to set the CCSID value.
CCSID is a multiplatform, multinational support mechanism for the management of character information using the Character Data Representation Architecture (CDRA). Providing the right CCSID setting is the key to whether your character data will convert correctly between different systems.
First, let's discuss why users might have character conversion issues. A user can use the Display file field definition (DSPFFD) command to take a look at any physical file field definition on System i5.
Figure 5. Physical file field definition on System i5
As shown in Figure 5, under each character field, there is a description called the CCSID. In our example, the CCSID value is set to 37. The CCSID value is used to represent characters and to convert those characters, as needed, to preserve their meaning. (For example, the CCSID value for English is 37, 297 for French, and so forth). DB2 tags character columns with CCSID, either explicitly using a data structure definition or implicitly using the job or system. If the two systems have different CCSID values, the receiving job converts the data to its own CCSID.
On System i5 computers, the received job's CCISD value comes from user profile's CCSID value for the user who started the job. Then, according to the configuration, the user's CCSID value either comes from the system value, or it can be defined by the users themselves. In our example, as shown in Figure 6, our system's CCSID value is 65535, which means that the received job's CCSID is also 65535, according to the configuration. A CCSID of 65535 indicates that the data is in hex format and should not be converted. But our application will get data from DB2 using Tomcat on System i5 to the browser (verified on Microsoft® Internet Explorer and Mozilla). Since System i5 and the browser use different code characters, character data conversion problems will occur.
Figure 6. System value of CCSID
Clearly, the easiest way to solve this problem is to change the CCSID value of the system. But that solution is not recommended, because it will affect the entire system. Here we provide more useful solutions for both in-process and out-of-process modules.
For an in-process module, Tomcat and the HTTP server run in the same process; the HTTP server acts as the received job and communicates between Tomcat and the Microsoft Internet Explorer browser. So setting the correct CCSID value for the HTTP server solves this problem for an in-process module. The CCSID value should be equal to the value that shows up after running the DSPFFD commands. In our example, as shown in Listing 1, you should add to Line 26 the DefaultFsCCSID 37 directive. The HTTP configure file will then tell the system to do the correct conversion.
For an out-of-process module, Tomcat and the HTTP server run in separate processes (even on separate systems). The Tomcat server needs to set a certain user ID to start the servlet engine, which starts the received job to communicate between Tomcat and the Microsoft Internet Explorer browser. So, defining the correct CCSID value for this specific user is the solution for the out-of-process module. As shown in Figure 3, there is a field to set the server user ID; the default value is QTMHHTTP. If you select this default user ID, then you should set its CCSID value by using the CHGUSRPRF command on the green-screen, as shown in Figure 7. Also the CCSID value should be equal to the value that shows up after running the DSPFFD command.
Figure7: Changing user profile's CCSID value
A useful tip: During our testing, we found that the primary language of a user's browser setting should be the same as the language the CCSID value represents on System i5. Otherwise, the user might get an error. In our example, we set our browser's primary language to English.
For more detailed information of CCSID on System i5, go to the iSeries Globalization Web page.
ASF Jakarta Tomcat 3.2.4 is an important component for delivering on demand solutions that run on the System i5 hardware platform. Relying on an HTTP server as its Web server, Tomcat provides a basic Web application server for System i5 customers. If customers want a basic, no-cost Web application server that supports servlets and JSPs, then Tomcat is an effective and easily used tool on System i5 servers.
Learn
-
iSeries Globalization Web page: Get details for CCSID on System i5.
-
IBM Systems: Want more? The developerWorks IBM Systems zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials.
-
developerWorks
technical events and webcasts: Stay current with developerWorks technical events and webcasts.
Get products and technologies
-
IBM trial software: Build your next development project with software for download directly from developerWorks.
Discuss
-
Participate in the IBM Systems forums, developerWorks
blogs, and get involved in the developerWorks community.
Chen Meng works as a Software Developer in the IBM China Software Development Lab. She has experience in development and testing on i5/OS. She has worked at IBM since 2005. She is currently working on integrated Internet collaboration projects on i5/OS. Her areas of expertise include WebSphere Application Server, Tomcat, and HTTP server testing and debugging. You can reach her at chenmeng@cn.ibm.com.
Jin Ye works as a Software Developer in the IBM China Software Development Lab. He joined IBM in 2003. He is an experienced tester for FVT, SVT on WebSphere Application Server, and HTTP server. His current area of focus is Apache HTTP server testing on i5/OS. You can reach him at jinye@cn.ibm.com.
Table of contents
Local resources
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
