About Tomcat

This topic provides information about the Apache Software Foundation Jakarta Tomcat servlet engine.

Important: Information for this topic supports the latest PTF levels for HTTP Server for i5/OS . It is recommended that you install the latest PTFs to upgrade to the latest level of the HTTP Server for i5/OS. Some of the topics documented here are not available prior to this update. See http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm Link outside Information Center

for more information.

The iSeries™ implementation of Apache Software Foundation (ASF) Jakarta Tomcat servlet engine (hereafter referred to as ASF Tomcat) provides a lightweight servlet engine that supports servlets, JavaServer pages (JSPs), and Web application archive (WAR) files. The HTTP Server for iSeries supports a module (mod_jk) that allows communication between the HTTP Server (powered by Apache) and ASF Tomcat.

For more in-depth technical information about ASF Tomcat, see http://jakarta.apache.org/tomcat/index.html Link outside Information Center . For more in-depth technical information about Java™ servlet technology (including the Java Servlet Specification, V2.2), see http://java.sun.com/products/servlet/ .

ASF Tomcat can be configured to run:

In-process where ASF Tomcat and the HTTP Server (powered by Apache) run in the same process and communicate through a Java native interface (JNI). Generally, running in-process is easier to configure and gives better performance. Running in-process also allows you to configure authentication through the HTTP server (including the ability to swap to an authenticated user profile) where out-of-process does not.
Out-of-process where ASF Tomcat runs in a separate process (this separate process can be on a different computer than the HTTP server) and communicates to the HTTP server through a TCP/IP sockets connection. It is important to note that if SSL support is configured between the Web Browser and the Web server, the connection between the Web server and the out-of-process ASF Tomcat server is not secured with SSL. Running out-of-process allows more flexibility in the number and type of processes that you can configure. An out-of-process configuration allows for:
- application and functional isolation of information
- reliability
- serviceability
- logically linking organizational synergies to application servlets
  For example, you may have different out-of-process ASF Tomcat servers on different systems to service specific functional areas of an organization, like shipping or accounting.

Configuration and administration of ASF Tomcat on the iSeries is accomplished through the IBM^® Web Administration for i5/OS™ interface. The ASF Tomcat Basic wizard is provided as an easy way to get started configuring servlets, JSPs, and WAR files.

ASF Tomcat supports the following:

ASF Tomcat 3.2.4
Java server pages (JSP) 1.1
Servlet 2.2 specification
In-process ASF Tomcat
Out-of-process ASF Tomcat using mod_jk ajp12 protocol support
Out-of-process ASF Tomcat using mod_jk ajp13 protocol support
Making SSL certificates and attributes associated with the client request available to the intended servlet, when configured as in-process or as out-of-process using the ajp13 protocol
HTTP Server (powered by Apache) virtual host mapping to ASF Tomcat
JDK 1.2 and 1.3

Directory structure

Directory	Description
`tomcat_home`	The tomcat_home directory is the base directory for ASF Tomcat. The tomcat_home 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 tomcat-home 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/webapps/ROOT`	This directory is required by ASF Tomcat.
`Tomcat_home/webapps/app1`	This directory is known as a document base directory. You may have several document base directories under the webapps directory. These represent and map a directory structure to a servlet or JSP application.
`Tomcat_home/webapps/app1/WEB-INF`	This directory contains the web.xml file for the application.
`Tomcat_home/webapps/app1/WEB-INF/classes`	This directory contains any Java class files and associated resources that are required for your application. This directory is searched prior to the tomcat_home/webapps/app1/WEB-INF/lib directory for any servlet .class file that is specified in the URL.
`Tomcat_home/webapps/app1/WEB-INF/lib`	This directory contains any JAR files and associated resources that are required for your application.
`Tomcat_home/conf`	This directory contains the server.xml and workers.properties configuration files.
`Tomcat_home/logs`	This directory contains all log files.
`Tomcat_home/work`	This directory is automatically generated by ASF Tomcat as a place to store intermediate files.
`Java/lib`	This directory is created as a place to put .jar and Class files that you want to add to the class path.

See User profiles and required authorities for HTTP Server for information about authority considerations for ASF Tomcat.

Log files

The jk.log file contains messages generated by mod_jk. It is important to note that this file is not erased or regenerated when the ASF Tomcat engine starts. Messages are appended to this file and the size of this file could grow very large if errors are being logged. You should periodically monitor the size of this file and reduce its size. By default, the jk.log is set to the logs directory under server_home (/www/server_name/logs/).

Each time the ASF Tomcat servlet engine is started, a set of log files is generated. These log files are all based on the configuration in the server.xml file. The default location of the log files is in the /logs directory under the tomcat_home directory.

The following is a description of each log file:

Log file	Description
`jasper.log`	This log file contains messages resulting from trying to start or run JSPs.
`servlet.log`	This log file contains messages generated as a result of a servlet running in the ASF Tomcat servlet engine. When a servlet is initialized a ServletConfig object is provided to the servlet. Contained within the ServletConfig object is a ServletContext object that provides methods for a servlet to communicate to the Servlet container, in this case Tomcat. On the ServletContext object is a log method that allows Web applications to log to the servlet.log file.
`tomcat.log`	This log file contains ASF Tomcat servlet engine messages.
`jvmstderr.txt`	This log file can contain messages from any Java code that does a System.err.println().
`jvmstdout.txt`	This log file can contain messages from any Java code that does a System.out.println().

Process description

Running in-process means that the ASF Tomcat module (mod_jk) uses the Java invocation API to:

Set up the JVM
Attach a given HTTP Server (powered by Apache) thread to the JVM
Run the servlet in the JVM

The servlet, written in Java, uses the JNI interface to call to the HTTP server to get the headers and data that accompany the HTTP request. The servlet container invokes the target servlet, packages the response, and sends the resulting response headers and data through the HTTP server using the JNI.

Running out-of-process means that the ASF Tomcat module (mod_jk) running in the HTTP server needs to take the headers and accompanying data, package it up into a protocol (ajp12 or ajp13), and then send that information across a TCP socket to the system where the JVM is running. This could be on the same system, or it could be on an different system.

The servlet running in the JVM does the following:

Receives the request from the socket
Finds the target servlet
Invokes the target servlet
Packages the response headers and data into an ajp12 or ajp13 response
Sends the response across the TCP socket to the HTTP server

The ASF Tomcat module running in the HTTP Server decodes the ajp12 or ajp13 response to retrieve the HTTP headers and data. The ASF Tomcat module sends the HTTP headers and data to the browser.