ref. http://www.akadia.com/download/soug/tomcat/html/tomcat_apache.html
The Tomcat server.xml file allows you to configure
Tomcat using a simple XML descriptor. This XML file is at the heart of Tomcat.
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.
1. Creating the Web Application Context (Location of the Web Application):
<!-- Tomcat Root Context -->
<Context path="/jsp" docBase="/www/webapp/jsp" debug="0" reloadable="false"
/>
-
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.
2. Disable Port 8080 (Port 8080 is only used in stand-alone mode)
<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 -->
<!-- (Uncommented for Productive Environment)
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="10" debug="0" connectionTimeout="20000"
useURIValidationHack="false" />
-->
The container that holds the components of a web application is the directory
structure in which it exists. The first step in creating a web application is
creating this structure. The following table contains the sample web
application and what each of its directories should contain.
|
The Web Application Directory Structure (Example)
|
|
Directory
|
Contains
|
|
/www/webapp/jsp
|
This is the root directory of the web application. All JSP and
XHTML files are stored here.
|
|
/www/webapp/jsp/WEB-INF
|
This directory contains all resources related to the application that are not
in the document root of the application. This is where your web application
deployment descriptor is located. Note that the WEB-INF directory is not part
of the public document. No files contained in this directory can be served
directly to a client.
|
|
/www/webapp/jsp/WEB-INF/classes
|
This directory is where servlet and utility classes are located.
|
|
/www/webapp/jsp/WEB-INF/lib
|
This directory contains Java Archive files that the web application depends
upon. For example, this is where you would place a JAR file that
contained a JDBC driver.
|
If you are deploying a servlet, then you have to add a servlet entry into the
web application's web.xml file. An example <servlet> element can be found in the following code
snippet.
<servlet>
<servlet-name>MyServlet</servlet-name>
<servlet-class>packagename.MyServlet</servlet-class>
<init-param>
<param-name>parameter</param-name>
<param-value>value</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
It isn't necessary to add all servlets to the web.xml file; it's only necessary when
the servlet requires additional information, such as initialization parameters.
|
The Sub-elements of a <servlet>
|
|
Sub-element
|
Description
|
|
<servlet-name>
|
The <servlet-name> element is simply the canonical name of
the deployed servlet.
|
|
<servlet-class>
|
The <servlet-class> sub-element
references the fully qualified class name of the servlet.
|
|
<init-param>
|
The <init-parameter> sub-element is an
optional parameter containing a name-value pair that is passed to the servlet
on initialization. It contains two sub-elements, <param-name> and <param-value>, which contain the name and value,
respectively, to be passed to the servlet.
|
|
<load-on-startup>
|
The <load-on-startup> sub-element
indicates the order in which each servlet should be loaded. Lower positive
values are loaded first. If the value is negative or unspecified, then the
container can load the servlet at anytime during startup.
|
Demystifying Tomcat 4's server.xml File
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: We will be focusing on the server.xml file as it is
configured for Tomcat 4.0.4.
<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
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:
-
<Logger>
-
<Realm>
-
<Valve>
-
<Host>
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.
