ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

Demystifying Tomcat 4's server.xml File
Pages: 1, 2

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:

  • <Logger>
  • <Realm>
  • <Valve>
  • <Context>

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:

  • <Logger>
  • <Loader>
  • <Realm>
  • <Manager>
  • <Ejb>
  • <Environment>
  • <Parameter>
  • <Resource>
  • <ResourceParams>

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.