Tomcat User's Guide

This document is an introduction to the Tomcat servlet container. It should be enough for anyone to install, configure, and deploy Tomcat. As well, it answers many questions common to new users. If you have any comments or suggestions about this document don't hesitate to send them to the Tomcat mailing lists.

This document began life as Tomcat: A Minimalistic User's Guide by Gal Shachor, and has been revised by many others. It should be considered a work in progress. Since the Tomcat source tree is constantly changing, the information herein may be out of date. The only definitive reference at this point is the source code.

"???" means I'm not sure if this should go in, or where it should go or be referred to as, if it does indeed belong. Other editorial comments are surrounded in [square brackets].

Other important documents:

• Jakarta FAQ Page
• Application Development manual - an alternative to the User's Guide, somewhat out-of-date
• Other Tomcat Documentation including HOWTOs for various web servers

Table of Contents

[This section needs to be revised to match current outline. Wouldn't it be nice if we used XSL to generate this file from an XML source?]

• About Tomcat
  • What is Tomcat?
  • Where can I download Tomcat?
  • Isn't Tomcat just JServ?
  • What are servlets? What are JSPs?
  • How do/can I contribute?
  • How come X, Y, or Z isn't working? Help!
• Installing Tomcat
  • File placement and environment setup
  • Starting and stopping Tomcat
  • Starting multiple instances w/individual server.xml files
  • Tomcat directory structure
  • Tomcat scripts
    
• Configuring Tomcat
  • Types of servlet containers
  • server.xml - Tomcat's main configuration file
  • web.xml - Default deployment descriptor
    
  • Web application/context security and authorization
  • tomcat-users.xml
  • JDBC realms
• Deploying Web Applications
• What is a Web Application?
• What is a WAR file?
• Deploying WAR files in Tomcat
  
  
• Tomcat Tutorials - ???
• Deploying application
• Creating your first web application ???
• Creating and configuring your first servlet ???
  
  
• Real World Configuration Tips
• Common Installation and Configuration Problems
  • "Bad command or filename" when executing Tomcat scripts
  • http://webserver:8007/ gives an HTTP 500
  • Apache <Directory> and <Location> directives ignored
  • Web server won't start when Tomcat is running
• Credits

About Tomcat: Q&A

See also the official Jakarta FAQ Page.

What is Tomcat?

Tomcat is the official reference implementation of the Java Servlet 2.2 and JavaServer Pages 1.1 technologies. Developed under the Apache license in an open and participatory environment, it is intended to be a collaboration of the best-of-breed developers from around the world.

Where can I download Tomcat?

At the Jakarta download page!

Isn't Tomcat just JServ?

This is a common misunderstanding. JServ is a Servlet API 2.0-compliant container that was created to be used with Apache. Tomcat is a complete re-write and is a Servlet API 2.2 and JSP 1.1-compliant container. Tomcat uses some of the code written for JServ, especially JServ's Apache server adapter, but this is where the similarities end.

What are servlets? What are JSPs?

In a nutshell, servlets are memory-resident Java programs, running inside a servlet container (e.g., Tomcat!). Because they're memory-resident, they can quickly respond to requests, as they do not incur the overhead of process creation and subsequent cleanup, unlike CGI-based scripting, e.g. perl, etc.

From Sun's servlet site:

"The Java^TM Servlet API provides web developers with a simple, consistent mechanism for extending the functionality of a web server and for accessing existing business systems. A servlet can almost be thought of as an applet that runs on the server side -- without a face."

...and about JSPs (JavaServer Pages), again from Sun's servlet site:

"JSP technology is an extension of the servlet technology created to support authoring of HTML and XML pages. It makes it easier to combine fixed or static template data with dynamic content."

JSP is comparable to other technologies such as PHP and ASP, which combine programming/scripting with a markup language like HTML. The key difference being the programming language of choice. For example, PHP uses a C/C++/Java hybrid, ASP uses VBScript, and JSP utilizes the full power of the Java programming language. There have been many comparisons of these technologies, and each has its place in the astute developer's toolbox.

All of the above information is available at Sun's Java website, which is a starting place for all the ins and outs of JSPs, servlets, etc. Your time spent with these technologies will be much more rewarding if you first read through the JavaServer Pages and servlet specifications!

How do/can I contribute?

Please do! See the Jakarta project contribution page, right here. You'll probably want to subscribe to the tomcat-dev mailing list.

How come X, Y, or Z isn't working? Help!

While we hope to cater to many common issues, we have undoubtedly missed some. For more help, try (in this order):

1. Your log files, in the logs subdirectory of your Tomcat installation. These are an untapped resource!
2. The Common problems section of this document.
3. Have a look through the Jakarta FAQ Page. Most installation and configuration questions can be found here.
4. Search the Tomcat user and developer list archives.
5. Post a question to the tomcat-user mailing list, which you must first subscribe to if you'd like to see any replies!

Installing Tomcat

File placement and environment setup

• Download the appropriate jakarta-tomcat [.zip | .gz | .Z] file.
• Unzip the file into some directory (say /usr/local or C:\). This should create a new subdirectory named "tomcat". [Does it still create "jakarta-tomcat" instead? If so, just rename it "tomcat".]
• Change directory to "tomcat" and set a new environment variable (TOMCAT_HOME) to point to the root directory of your Tomcat hierarchy. The exact directory may change from system to system; check your local filesystem to be sure where Tomcat is installed.
  1. On Win32 systems you should type:
     set TOMCAT_HOME=c:\tomcat
  2. On UNIX (using bash/sh) you should type:
     TOMCAT_HOME=/usr/local/tomcat ; export TOMCAT_HOME
  3. On UNIX (using tcsh) you should type:
     setenv TOMCAT_HOME=/usr/local/tomcat
• Set the environment variable JAVA_HOME to point to the root directory of your JDK hierarchy, then add the Java interpreter to your PATH environment variable. The exact directory may change from system to system; check your local filesystem to be sure where Java is installed.
  1. Win32:
     set JAVA_HOME=c:/jdk1.2
     set PATH=%PATH%;%JAVA_HOME%\bin
  2. Unix (bash/sh):
     set JAVA_HOME=/user/local/java/jdk1.2; export JAVA_HOME
     set PATH=$PATH:$JAVA_HOME/bin; export PATH
     
  3. Unix (tcsh):
     setenv JAVA_HOME=/user/local/java/jdk1.2
     setenv PATH=$PATH:$JAVA_HOME/bin
     

That's it! You can now execute Tomcat and it will run as a stand-alone servlet container.

Once you're sure they work, these environment variables should probably be set in a config file: C:/AUTOEXEC.BAT for Windows, ~/bash_profile or ~/[what is it for tcsh?]

Starting and stopping Tomcat

You start and stop Tomcat using the scripts in the bin subdirectory of TOMCAT_HOME.

To start Tomcat execute:

On UNIX: bin/startup.sh

On Win32: bin\startup

To stop Tomcat execute:

On UNIX: bin/shutdown.sh

On Win32: bin\shutdown

Starting multiple instances with individual server.xml files

This might not make a whole lot of sense until you read the next section explaining Tomcat's directory structure, as well as Configuring Tomcat. You may want to come back here afterwards.

By default, Tomcat will use TOMCAT_HOME/conf/server.xml for configuration, which by default, uses TOMCAT_HOME as its base for the contexts. You can change this by using the "-f /path/to/server.xml" option, with a different server configuration file and setting the home attribute of the ContextManager element. You need to set up the required files inside the home:

• webapps/ - all war files will be expanded and all subdirectories added as contexts.
• conf/ directory - you can store a special web.xml and other configuration files.
• logs/ - all logs will go to this directory instead of the main TOMCAT_HOME/logs/.
• work/ - work directories for the contexts.

If the home attribute of the ContextManager element in server.xml is relative, it will be relative to the current working directory.

The Tomcat directory structure

Assuming you extracted the Tomcat binary distribution you should have the following directory structure under TOMCAT_HOME:

Directory	Contents
bin	Startup/shutdown scripts and other useful files.
conf	Configuration files including server.xml (Tomcat's main configuration file) and web.xml (default values for the various web applications deployed in Tomcat.).
doc	Miscellaneous documents regarding Tomcat.
lib	Various jar files that are used by Tomcat. Any file in this directory is appended to Tomcat's classpath.
logs	This is where Tomcat places its log files by default.
src	The servlet API source files. Don't get excited, though; these are only the empty interfaces and abstract classes that should be implemented by any servlet container.
webapps	Sample web applications. Any .war files placed here will be automatically expanded. See Deploying WAR files.

Additionally you can, or Tomcat will, create the following directories:

work	Where Tomcat places intermediate files (such as compiled JSP files) during its work. If you delete this directory while Tomcat is running you will not be able to execute JSP pages.
classes	Any class that you add to this directory will find its place in Tomcat's classpath.

Tomcat scripts

This section is not required reading, as the default functionality provided by the aforementioned startup and shutdown scripts is sufficient for most users to get started. If everything is working so far, skip ahead to Configuring Tomcat. Come back to this section when you'd like more information on these scripts, which you undoubtedly will.

Tomcat is a Java program, and therefore it is possible to execute it from the command line, after setting several environment variables. However, setting each environment variable and following the command line parameters used by Tomcat is error prone and tedious. Instead, the Tomcat development team provides a few scripts to ease starting and stopping Tomcat.

Note: The scripts are only a convenient way to start/stop. You can modify them to customize the CLASSPATH, environment variables such as PATH and LD_LIBRARY_PATH, etc., so long as a correct command line is generated for Tomcat.

The following table presents the scripts that are most important for the common user:

The script which has the most significance for users is tomcat (tomcat.sh/tomcat.bat). The other Tomcat related scripts serve as a simplified single-task oriented entry point to the tomcat script (set different command line parameters etc.).

Tomcat scripts: a closer look

A closer look at tomcat.sh/tomcat.bat yields that it performs the following actions:

These behaviors, especially CLASSPATH setting, have changed with Tomcat 3.2. It is best to look directly at the scripts for details on what variables are set and what class files are loaded. [??? - delete entire section pending reexamination?]

As you can see, the Win32 version of tomcat.bat pales in comparison to the Unix one. Especially it does not guess the values of TOMCAT_HOME and JAVA_HOME and it also doesn't take add all of the .jar files into the classpath.

Servlet Container Types

Tomcat, like any servlet container, is meant to run behind a web server. The web server takes care of receiving HTTP requests from client browsers; the servlet container takes care of serving Servlets and JSPs for those URLs that request them.

In Tomcat's case, there are three different modes of execution Tomcat supports.

Stand-alone servlet containers

These are an integral part of the web server. This is the case when using a Java-based web server, for example the servlet container that is part of the JavaWebServer. Stand-alone is the default mode used by Tomcat. Most web servers, however, are not Java-based, which leads us to the next two container types.

In-process servlet containers

The servlet container is a combination of a web server plugin and a Java container implementation. The web server plugin opens a JVM inside the web server's address space and lets the servlet container run in it. If a certain request should execute a servlet, the plugin takes control over the request and passes it (using JNI) to the servlet container. An in-process container is suitable for multi-threaded single-process servers and provides good performance but is limited in scalability.

Out-of-process servlet containers

The servlet container is a combination of a web server plugin and a Java container implementation that runs in a JVM outside the web server. The web server plugin and the Java container JVM communicate using some IPC mechanism (usually TCP/IP sockets). If a certain request should execute a servlet the plugin takes control over the request and passes it (using IPC) to the servlet container. The response time of an out-of-process engine is not as good as in the in-process one but the out-of-process engine performs better in many measurable ways (scalability, stability, etc.).

Tomcat can be used as either a stand-alone container (mainly for development and debugging) or as an add-on to an existing web server (currently Apache, IIS and Netscape servers are supported). This means that whenever you are deploying Tomcat you will have to decide how to use it and, if you select options 2 or 3, you will also need to install a web server adapter.

If this is your first time configuring Tomcat and you plan on integrating it with a web server, you're better off initially running it stand-alone. You'll be better able to isolate errors during integration with your web server when you do so in the future - "Is Tomcat or my web server at fault for the error I'm seeing?"

Configuring Tomcat

Tomcat's configuration is based on two files:

1. server.xml - Tomcat's global configuration file.
2. web.xml - Default deployment descriptor.

server.xml - Tomcat's main configuration file

The elements in server.xml (found in the conf subdirectory of TOMCAT_HOME) are described below. Following along with the default server.xml in another window is helpful. The default server.xml file has many comments which may supersede the comments below. This is more of a reference section than a how-to.

<Server>	The topmost element. <Server> defines a single Tomcat server. Generally you should not bother with it.
	<xmlmapper:debug> You'll most likely never have to touch this, unless you're worried about how Tomcat is registering the contents of this server.xml file. Even if you are concerned, the startup output found in Tomcat's main log file will usually be sufficient for this purpose. Attributes: level. A value of "0" means "no output". "9" meaning "most everything". <Logger> This element defines a Logger object, equivalent to a log file. Currently there are loggers for the servlets (where the ServletContext.log() goes), JSP files and the tomcat runtime. Attributes: name. Identifies the logger. One of "tc_log", "servlet_log", or "JASPER_LOG". path. Output file, relative to TOMCAT_HOME. If you omit a "path" value, then stderr & stdout are used. verbosityLevel. In order of increasing verbosity; one of "FATAL", "ERROR", "WARNING", "INFORMATION", or "DEBUG". <ContextManager> A ContextManager specifies the configuration and structure for a set of ContextInterceptors, RequestInterceptors, Contexts and their Connectors. Attributes: debug. A value of "0" means "no output". "9" meaning "most everything". home. The base location for the webapps, conf, and logs directories, as well as all defined contexts. It is used to start Tomcat from a directory other than TOMCAT_HOME. The default value for this attribute is TOMCAT_HOME. workDir. The name of the working directory, relative to the above home attribute. <ContextInterceptor> <RequestInterceptor> These interceptors listen for certain events that happen in the ContextManager. For example, the ContextInterceptor listens for startup and shutdown events of Tomcat, and the RequestInterceptor watches the various phases that user requests need to pass during its service. Tomcat's administrator doesn't need to know much about the interceptors; a developer on the other hand should know that this is how "global" type of operations can be implemented in Tomcat (for example, security and per request logging). <Connector> The Connector represents a connection to the user, either through a web server or directly to the user's browser (in a stand-alone configuration). The Connector object is the one responsible for the management of the Tomcat worker threads and for read/write requests/responses from the sockets connecting to the various clients. Attributes: className. Which Connector to use. We will describe how to use this Connector configuration later in the document. <Parameter> Connector initialization parameters. You may have as many of these elements as required under each Connector. Attributes: name. So far, one of "handler", "port", "socketFactory". value. The appropriate value. <Context> Each Context represents a path in the Tomcat hierarchy where you place a web application. Attributes: path.The context path for a particular web application, which is the prefix of a request URI that tells Tomcat which Context should be used to process this request. This attribute is required, and must start with a slash ('/') character. docBase. The root of your web application. This can be a full path or relative to the ContextManager's home. This is Tomcat's version of Apache's "DocumentRoot" directive. reloadable. When developing a servlet it is very convenient to have Tomcat automatically reload it, allowing you to fix bugs and have Tomcat test the new code without the need to restart the container. To turn on servlet reloading set the reloadable flag to true. Detecting changes however is time consuming; moreover, since the new servlets are getting loaded in a new class-loader object there are cases where this class-reloading trigger casts errors. To avoid these problems you can set the reloadable flag to false; this will disable the autoreload feature. trusted. Trusted allows you to access tomcat internal objects with FacadeManager. debug. A value of "0" means "no output". "9" meaning "most everything". <Host> Contains <Context> elements. The <Host> element is used to configure per-virtual host Contexts. Attributes: name: The fully-qualified hostname or IP address of the virtual host. </ContextManager>
</Server>

web.xml - Default deployment descriptor

A detailed description of web.xml and the web application structure (including directory structure and configuration) is available in chapters 9, 10 and 13 of the Servlet API Spec and we are not going to write about it. Developing Applications with Tomcat covers web application and deployment with Tomcat. It is required reading if you're not going to take the time to read through the Servlet API Spec!

There is a small Tomcat "feature" that is related to web.xml. Tomcat lets the user define default web.xml values for all contexts by putting a default web.xml file in the conf subdirectory of TOMCAT_HOME. When constructing a new Context, Tomcat uses the default web.xml file as the base configuration, and then applies the application specific web.xml (the application's WEB-INF/web.xml file) settings.

This means that in Tomcat, you can get away with an empty web.xml file, containing only the element <web-app/>, or (more realistically) containing only the elements (e.g. mappings and mime-types) you need. However, this will limit your webapp's portability, so it is recommended to use a full web.xml file. You may instead want to copy TOMCAT_HOME/conf/web.xml and modify it.

We cover certain aspects of web.xml in subsequent sections, where it pertains to application deployment and interaction with Tomcat.

Deploying Web Applications

What is a Web Application?

[??? - move this section up above the Configuring Tomcat section? It's not clear whether we should teach about webapps before or after we introduce server.xml et al.]

A Web Application (or "webapp") is a concept that was introduced in the Servlet Specification version 2.2. [2.1?] You should definitely read the spec for the full story. From the spec (chapter 9):

A web application is a collection of servlets, html pages, classes, and other resources that can be bundled and run on multiple containers from multiple vendors. A web application is rooted at a specific path within a web server. For example, a catalog application could be located at http:// www.mycorp.com/catalog. All requests that start with this prefix will be routed to the ServletContext which represents the catalog application.

A servlet container can also establish rules for automatic generation of web applications. For example a ~user/ mapping could be used to map to a web application based at /home/user/ public_html/.

[...]

A web application exists as a structured hierarchy of directories. The root of this hierarchy serves as a document root for serving files that are part of this context. For example, for a web application located at /catalog in a web server, the index.html file located at the base of the web application hierarchy can be served to satisfy a request to /catalog/index.html.

A special directory exists within the application hierarchy named "WEB-INF". This directory contains all things related to the application that aren't in the document root of the application. It is important to note that the WEB-INF node is not part of the public document tree of the application. No file contained in the WEB-INF directory may be served directly to a client.

The contents of the WEB-INF directory are:

• /WEB-INF/web.xml deployment descriptor
• /WEB-INF/classes/* directory for servlet and utility classes. The classes in this directory are used by the application class loader to load classes from.
• /WEB-INF/lib/*.jar area for Java ARchive files which contain servlets, beans, and other utility classes useful to the web application. All such archive files are used by the web application class loader to load classes from.

Sample Web Application Directory Structure

Illustrated here is a listing of all the files in a sample web application:

/index.html
/howto.jsp
/feedback.jsp
/images/banner.gif
/images/jumping.gif
/WEB-INF/web.xml
/WEB-INF/lib/jspbean.jar
/WEB-INF/classes/com/mycorp/servlets/MyServlet.class
/WEB-INF/classes/com/mycorp/util/MyUtils.class

You can deploy a WAR file that is present on the local filesystem by adding a <Context> tag to TOMCAT_HOME/conf/server.xml. For example:

<Context path="/mywebapp" 
  docBase="/home/alex/webapps/mywebapp" 
  reloadable="true" >
</Context>

What is a WAR file?

"WAR. Huh! What is it good for?" - Edwin Starr

A WAR (or "web archive") file is simply a packaged webapp directory. It is created using the standard Java jar tool. For example:

cd /home/alex/webapps/mywebapp 
jar cf mywebapp.war *

Deploying WAR files in Tomcat

Currently (as of version 3.2) the procedure for deploying a new WAR file is:

1. Stop Tomcat.

2. Delete existing deployment. If you have previously deployed "foo.war" in TOMCAT_HOME/webapps, then it has been unpacked into webapps/foo/... You must delete this directory and all its contents. On Unix, this can be done with:

   rm -r $TOMCAT_HOME/webapps/foo

3. Copy WAR file to TOMCAT_HOME/webapps/.
4. Start Tomcat.

This process may become easier in the future. A "deploy tool" is on the Tomcat "to-do" list.

Note that if you deploy a WAR file in this manner, you do not need to make any changes to server.xml -- it will automatically be recognized and activated when the server starts. However, if you wish to specify non-default options for this webapp, you may do so by adding an element like <Context docBase="webapps/foo" ... to server.xml.

See also How do I deploy a WAR file in Tomcat? in the jGuru FAQ.

Tomcat Tutorials

These tutorials will be run with the assumption that Tomcat is operating as a stand-alone container. Like we said before, it can be helpful to understand Tomcat's functionality, irrespective of the particular web server you're using. Trying to get more than one thing working at once usually leads to more problems than its worth. Integration will be covered later in subsequent sections.

Real World Configuration Tips

By default the Tomcat distribution comes with a naive configuration whose main goal is to promote first time user experience and an "out of the box" operation... This configuration however is not the best way to deploy Tomcat on real sites. For example, real sites may require some performance tuning and site-specific settings (additional path elements for example). This section will try to get you started by directing you to the first steps that should be taken before publishing a Tomcat based site.

Modify and Customize the Batch Files

As stated in the previous sections, the startup scripts are here for your convenience. Yet, sometimes the scripts that are needed for deployment should be modified:

• To set resource limits such as maximum number of descriptors.
• To add new CLASSPATH entries (for example, JDBC drivers).
• To add new PATH/LD_LIBRARY_PATH entries (for example, JDBC drivers DLLs).
• To modify the JVM command line settings.
• Make sure that you are using a specific JVM (out of the two or three JVMs installed on your machine).
• To switch user from root to some other user using the "su" UNIX command.
• Your pet reason.

Some of these changes can be done without explicit changes to the basic scripts; for example, the tomcat script can use an environment variable named TOMCAT_OPTS to set extra command line parameters to the JVM (such as memory setting etc.). On UNIX you can also create a file named ".tomcatrc" in your home directory and Tomcat will take environment information such as PATH, JAVA_HOME, TOMCAT_HOME and CLASSPATH from this file. On NT however (and also on UNIX when the modifications are for something such as the JVM command line) you are forced to rewrite some of the startup script...

Modify the Default JVM Settings

The default JVM settings in the tomcat script are very naïve; everything is left for defaults. There are a few things that you should consider to improve your Tomcat performance:

1. Modify your JVM memory configuration. Normally the JVM allocates an initial size for the Java heap and that's it, if you need more then this amount of memory you will not get it.
   Nevertheless, in loaded sites, giving more memory to the JVM improves Tomcat's performance. You should use command line parameters such as -Xms/-Xmx/-ms/-mx to set the minimum/maximum size of the Java heap (and check to see if the performance was improved).
2. Modify your JVM threading configuration. The SUN JDK1.2.2 for Linux comes with support for both, green and native threads. In general native threads are known to provide improved performance for I/O bound applications, green threads on the other hand put less stress on the machine. You should experiment with these two threading models and see which model is better for your site (in general, native threads are better).
3. Select the best JVM for the task. There are several JVM vendors, for example on Linux there are today (21/03/2000) two product level JVMs: the SUN JDK1.2.2 and the IBM JDK1.1.8. If your application does not require a specific JDK functionality, you should benchmark the two JVMs and select the better one. In my (Gal Shachor) internal tests I found the IBM JVM significantly faster than the one created by SUN, you should check that for yourself and make a calculated decision.

Modify your Connectors

The Connectors, as configured in Tomcat's default server.xml contains two Connectors configured as in the next server.xml fragment:

        <!-- (1) HTTP Connector for stand-alone operation -->
        <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
            <Parameter
                name="handler"
                value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
            <Parameter
                name="port"
                value="8080"/>
        </Connector>

        <!-- (2) AJPV12 Connector for out-of-process operation -->
        <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
            <Parameter
                name="handler"
                value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
            <Parameter
                name="port"
                value="8007"/>
        </Connector>

1. Is a Connector that listens on port 8080 for incoming HTTP requests. This connector is needed for stand-alone operation.
2. Is a Connector that listens on port 8007 for incoming AJPV12 requests. This connector is needed for web-server integration (out-of-process servlet integration).

It is clear that a sane Tomcat deployment will use either an out-of-process servlet integration or a stand-alone operation, removing the unnecessary Connector is important.

Use a Thread Pool in your Connectors

Tomcat is a multi-threaded servlet container this means that each request needs to be executed by some thread. By default when a request arrives Tomcat creates a new thread, starts it and has it serve the request. This behavior is problematic for loaded sites because:

• Starting and stopping a thread for every request puts a needless burden on the operating system and the JVM.
• It is hard to limit the resource consumption. If 300 requests arrive concurrently Tomcat will open 300 threads to serve them and allocate all the resources needed to serve all the 300 requests at the same time. This causes Tomcat to allocate much more resources (CPU, Memory, Descriptors...) than it should and it can lead to low performance and even crashes if resources are exhausted.

The solution for these problems is to use a thread pool. Servlet containers that are using a thread pool relieve themselves from directly managing their threads. Instead of allocating new threads; whenever they need a thread they ask for it from the pool, and when they are done, the thread is returned to the pool. The thread pool can now be used to implement sophisticated thread management techniques, such as:

1. Keeping threads "open" and reusing them over and over again. This saves the trouble associated with creating and destroying threads continuously.
   • Usually the administrator can instruct the pool not to keep too many idle threads, freeing them if needed.
2. Setting an upper bound on the number of threads used concurrently. This prevents the resources allocation problem associated with unlimited thread allocation.
   • If the container maxed out to the threads upper limit, and a new request arrives, the new request will have to wait for some other (previous) request to finish and free the thread used to service it.

You can refine the techniques described above in various ways, but these are only refinements. The main contribution of thread pools is thread-reuse and having a concurrency upper bound that limits resource usage.

Using a thread pool in Tomcat is a simple move; all you need to do is to use a PoolTcpConnector in your <Connector> configuration. For example the following server.xml fragment defines ajpv12, pooled Connector:

<!-- A pooled AJPV12 Connector for out-of-process operation -->
        <Connector className="org.apache.tomcat.service.PoolTcpConnector">
            <Parameter
                name="handler"
                value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
            <Parameter
                name="port"
                value="8007"/>
        </Connector>

This fragment is very simple and the (default) pool behaviour instructed by it is:

• Upper bound for concurrency of 50 threads.
• When the pool has more then 25 threads standing idle it will start to kill them.
• The pool will start 10 threads on creation, and it will try to keep 10 vacant threads (as long as the upper bound is kept).

Configuring the Thread Pool

<!-- A pooled AJPV12 Connector for out-of-process operation --> <Connector className="org.apache.tomcat.service.PoolTcpConnector"> <Parameter name="handler" value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/> <Parameter name="port" value="8007"/> <Parameter name="max_threads" value="30"/> <Parameter name="max_spare_threads" value="20"/> <Parameter name="min_spare_threads" value="5" /> </Connector>

As can be seen the pool has 3 configuration parameters:

• max_threads - defines the upper bound to the for the concurrency, the pool will not create more then this number of threads.
• max_spare_threads - defines the maximum number of threads that the pool will keep idle. If the number of idle threads passes the value of max_spare_threads the pool will kill these threads.
• min_spare_threads - the pool will try to make sure that at any time there is at least this number of idle threads waiting for new requests to arrive. min_spare_threads must be bigger then 0.

Disable Servlet Auto-Reloading

Servlet auto-reloading is really useful for development time. However it is very expensive (in performance degradation terms) and may put your application in strange conflicts when classes that were loaded by a certain classloader cannot co-operate with classes loaded by the current classloader.

So, unless you have a real need for class reloading during your deployment you should turn off the reloadable flag in your contexts.

Start Tomcat from /etc/inittab

Unfortunately the adapters developed for Apache (or for any of the other servers) cannot start Tomcat yet. On UNIX however, you can use the init table to start Tomcat automatically upon machine startup. FIXME:

Credits

Tomcat was originally written by Sun Microsystems, and has been improved (we hope) by a cast of thousands.

This document was created by:

• Gal Shachor

With help from (in alphabetical order):

• Jonathan Bnayahu
• Alex Chaffee
• Fiona Czuczman
• Costin Manolache
• Rob Slifka