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


Using Tomcat Demystifying Tomcat 4's server.xml File

by James Goodwill
07/31/2002

The Tomcat server.xml file allows you to configure Tomcat using a simple XML descriptor. This XML file is at the heart of Tomcat. In this article, I will focus on the configuration of all of the major Tomcat components found in the server.xml file. To examine these components, open your server.xml file, which can be found in the conf/ directory of your Tomcat installation. The following listing contains a simplified version of the default server.xml file.

Note: In this article, we will be focusing on the server.xml file as it is configured for Tomcat 4.0.4.

Example 1. A simple server.xml file

<Server port="8005" shutdown="SHUTDOWN" debug="0">
  <Service name="Tomcat-Standalone">
    <Connector className="org.apache.catalina.connector.http.HttpConnector"
      port="8080" minProcessors="5" maxProcessors="75"
      enableLookups="true" redirectPort="8443"
      acceptCount="10" debug="0" connectionTimeout="60000"/>
    <Engine name="Standalone" defaultHost="localhost" debug="0">
      <Logger className="org.apache.catalina.logger.FileLogger"
        prefix="catalina_log." suffix=".txt"
        timestamp="true"/>
      <Realm className="org.apache.catalina.realm.MemoryRealm" />
      <Host name="localhost" debug="0" appBase="webapps" unpackWARs="true">
        <Valve className="org.apache.catalina.valves.AccessLogValve"
          directory="logs" prefix="localhost_access_log." suffix=".txt"
          pattern="common"/>
        <Logger className="org.apache.catalina.logger.FileLogger"
         directory="logs" prefix="localhost_log." suffix=".txt"
         timestamp="true"/>
        <Context path="/examples" docBase="examples" debug="0"
         reloadable="true">
          <Logger className="org.apache.catalina.logger.FileLogger"
           prefix="localhost_examples_log." suffix=".txt"
           timestamp="true"/>
         </Context>
      </Host>
    </Engine>
  </Service>
</Server>

The <Server> Element

The first element found in the server.xml file is the <Server> element. This element represents the entire Tomcat container. It is used as a top-level element for a single Tomcat instance.

The <Server> element is defined by the org.apache.catalina.Server interface. The Server interface is a simple singleton element that represents the entire Tomcat JVM. Each <Server> may contain one or more Service instances. The following list defines the possible attributes that can be set for the <Server> element.

className: Names the fully-qualified Java class name of the class that implements the org.apache.cataline.Server interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.core.StandardServer.

port: Names the TCP/IP port number to which the server listens for a shutdown command. The TCP/IP client that issues the shutdown command must be running on the same computer that is running Tomcat. This attribute is required.

shutdown: Defines the command string to shut down Tomcat. It must be received by the server on the named port. This attribute is required.

The <Server> element defined in the default server.xml file is contained in the following code snippet:

<Server port="8005"
  shutdown="SHUTDOWN"
  debug="0">

Note: The debug attribute is available to all Tomcat elements. It states the debug level to use when logging messages to a defined Logger. We will look at a Logger definition later in this article.

The <Server> element cannot be configured as a child of any elements. It can be configured as a parent to the <Service> element.

The <Service> Element

Related Reading

Ant: The Definitive Guide
By Jesse E. Tilly, Eric M. Burke

The next element in the server.xml file is the <Service> element, which acts as a container for one or more <Connector> elements that share a single <Engine> element. One or more <Service> elements may be nested inside of a single <Server> element. The <Service> element is defined by the org.apache.catalina.Service interface. The following list describes the possible <Service> element attributes.

className: Names the fully-qualified Java class name of the class that implements the org.apache.cataline.Service interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.core.StandardService.

shutdown: Defines the command string to shut down Tomcat. It must be received by the server on the named port. This attribute is required.

The <Service> element found in our server.xml file describes a service that represents a stand-alone Tomcat service that will handle all direct requests received by Tomcat.

<Service name="Tomcat-Standalone">

Note: I will discuss how to add additional <Service> elements in a subsequent article.

The <Service> element can be configured as a child of the <Server> element. It can be configured as a parent to the <Connector> and <Engine> elements.

The <Engine> Element

The third element in the server.xml file is the <Engine> element, which represents the Catalina servlet container. There can only be one <Engine> element for each defined <Service>. This single <Engine> component will receive all requests received by all of the defined <Connector> components. The <Engine> element must be nested immediately after the <Connector> elements, inside of its owning <Service> element.

The <Engine> element is defined by the org.apache.catalina.Engine interface. The following list describes the possible <Engine> element attributes.

className: Names the fully-qualified Java class name of the class that implements the org.apache.cataline.Engine interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.core.StandardEngine.

defaultHost: Names the host name to which all requests will be defaulted if not otherwise named. The named host must be defined by a child <Host> element.

name: Defines the logical name of this engine. The name selected is arbitrary, but it is required.

The following code snippet contains the <Engine> element defined in the server.xml file. The element defines an engine named Standalone with a default host of localhost.

<Engine name="Standalone" defaultHost="localhost" debug="0">

The <Engine> element can be configured as a child of the <Service> element. It can be configured as a parent to the following elements:

The <Host> Element

The <Host> element defines the virtual hosts that are contained in each instance of a Catalina <Engine>. Each <Host> can be a parent to one or more Web applications, which are represented by a <Context> component, which will be described in the following section.

You must define at least one <Host> for each Engine element. The possible attributes for the <Host> element are described below.

className: Names the fully-qualified Java class name of the class that implements the org.apache.catalina.Host interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.core.StandardHost.

appBase: Defines the directory for this virtual host. This directory is the pathname of the Web applications to be executed in this virtual host. This value can be an absolute path, or a path that is relative to the <CATALINA_HOME> directory. If this value is not specified, the relative value webapps will be used.

unpackWARs: Determines if WAR files should be unpacked, or run directly from the WAR file. If not specified, the default value is true.

name: Defines host name of this virtual host. This attribute is required, and must be unique among the virtual hosts running in this servlet container.

The <Host> element defined for the Standalone <Engine> is listed in the following code snippet:

<Host name="localhost" debug="0" appBase="webapps" unpackWARs="true">

The host definition defines a host named localhost that can be accessed by opening the URL http://localhost:8080/.

Note: The port 8080 appended to the previous URL is defined by the <Connector> element, which will be described later in this article.

The <Host> element is configured as a child of the <Engine> element. It can be configured as a parent to the following elements:

The <Context> Element

The <Context> element is the most commonly used element in the server.xml file. It represents an individual Web application that is running within a defined <Host>. There is no limit to the number of contexts that can be defined within a <Host> element. Each <Context> definition must have a unique context path, which is defined by the path attribute. The possible attributes for the <Context> element are described below.

className: Names the fully-qualified Java class name of the class that implements the org.apache.catalina.Host interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.core.StandardContext.

cookies: Determines if you want cookies to be used for session identifier. The default value is true.

crossContext: When set to true, allows the ServletContext.getContext() method to successfully return the ServletContext for other Web applications running in the same host. The default value is false, which will prevent the access of cross-context access.

docBase: Defines the directory for the Web application associated with this <Context>. This is the pathname of a directory that contains the resources for the Web application.

path: Defines the context path for this Web application. This value must be unique for each <Context> defined in a given <Host>.

reloadable: If set to true, causes Tomcat to check for class changes in the WEB-INF/classes/ and WEB-INF/lib directories. If these classes have changed, the application owning these classes will automatically be reloaded. This feature should only be used during development. This setting will cause severe performance degradation, and therefore should be set to false when in a production environment.

wrapperClass: Defines the Java class name of the org.apache.catalina.Wrapper implementation class that will be used to wrap servlets managed by this Context. If not specified, the standard value org.apache.catalina.core.StandardWrapper will be used.

useNaming: Set this value to true if you want Catalina to enable JNDI. The default value is true.

override: Set this value to to override the DefaultContext configuration.The default value is false.

workDir: Defines the pathname to a scratch directory that will be used by this <Context> for temporary read and write access. The directory will be made visible as a servlet context attribute of type java.io.File, with the standard key of java.servlet.context.tempdir. If this value is not specified, Tomcat will use the work directory.

The <Context> element that defines the /examples application is included in the following code snippet:

<Context path="/examples" docBase="examples" debug="0"
reloadable="true">

The context definition defines a Web application named /examples that will have all of its resources stored in the directory <TOMCAT_HOME>/Webapps/examples. This context also states that this application will be reloaded when class files are changed.

The <Context> element is configured as a child of the <Host> element. It can be configured as a parent to the following elements:

Note: If you do not have special configuration needs, you can use the default context configuration that is described in the default web.xml file, which can be found in the <CATALINA_HOME>/conf/ directory.

The <Connector> Element

The final element we are going to examine is the <Connector> element. The <Connector> element defines the component that does the actual managing of requests and responses to and from a calling client. The <Connector> element is defined by the org.apache.catalina.Connector interface. The <Connector> element's attributes are described below.

className: Names the fully-qualified Java class name of the class that implements the org.apache.catalina.Host interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.Connector interface.

enableLookups: Determines whether DNS lookups are enabled. The default value for this attribute is true. When DNS lookups are enabled, an application calling request.getRemoteHost() will be returned the domain name of the calling client. Enabling DNS lookups can have an unfavorable impact on performance, so this value should most often be set to false.

redirectPort: Names the TCP/IP port number to which a request should be redirected, if it comes in on a non-SSL port, and is subject to a security constraint with a transport guarantee that requires SSL.

name: Defines host name of this virtual host. This attribute is required, and must be unique among the virtual hosts running in this servlet container.

The <Connector> element is configured as a child of the <Service> element. It cannot be configured as a parent to any element.

The HTTP Connector

The most common Tomcat connector is the HTTP connector, which is preconfigured with Tomcat. Like all connectors, the HTTP connector implements the org.apache.catalina.Connector interface, which automatically associates it with the connector attributes described above, but it also defines a set of attributes that are specific to the HttpConnector. These additional attributes are listed here.

port: Names the TCP/IP port number on which the connector listens for requests. The default value is 8080. If you want Tomcat to process requests using the default HTTP port of 80, simply set this attribute to 80.

address: This attribute is used for servers with more than one IP address. It specifies which address will be used for listening on the specified port. If this attribute is not specified, this named port number will be used on all IP addresses associated with this server.

bufferSize: Specifies the size, in bytes, of the buffer to be provided for use by input streams created by this connector. Increasing the buffer size can improve performance, at the expense of higher memory usage. The default value is 2048 bytes.

className: Names the fully-qualified Java class name of the HTTP connector class. This value must equal org.apache.cataline.connector.http.HttpConnector.

enableLookups: Same for all connectors.

proxyName: Specifies the server name to use if this instance of Tomcat is behind a firewall. This is an optional attribute.

proxyPort: Specifies the HTTP port to use if this instance of Tomcat is behind a firewall. An optional attribute.

minProcessors: Defines the minimum number of processors, or instances, to start at initialization time. The default value is 5.

maxProcessors: Defines the maximum number of allowed processors, or instances, that can be started. The default value is 20. An unlimited number of processors can be started if the value of the maxProcessors attribute is set to a number less than zero.

acceptCount: Specifies the number of requests that can be queued on the listening port. The default value is 10.

connectionTimeout: Defines time, in milliseconds, before a request terminates. The default value is 60000 milliseconds. To disable connection timeouts, the connectionTimeout value should be set to -1.

An example <Connector> defining a HTTP connector is contained in the following code snippet:

<Connector className="org.apache.catalina.connector.http.HttpConnector"
  port="8080"
  minProcessors="5"
  maxProcessors="75"
  enableLookups="true"
  redirectPort="8443"
  acceptCount="10"
  debug="0"
  connectionTimeout="60000"/>

This <Connector> defines an HttpConnector that listens for requests on port 8080. It starts with a minimum of five processors and can start up to as many as 75 processors.

Up Next: in the next Tomcat article, I will take another look at the server.xml while we configure Tomcat to receive requests from the Apache Web server.

James Goodwill is the co-Founder of Virtuas Solutions, LLC, a Colorado-based software consultancy.


Read more Using Tomcat columns.

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.