craigmcc 01/08/24 20:37:39
Added: webapps/tomcat-docs/config context.xml host.xml
Log:
Add new-style docs for the <Host> and <Context> elements:
TODO: Nested Components (DefaultContext, Loader, Logger, Manager, Realm,
Resources, Valve) and update the table of contents on the index page.
Revision Changes Path
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml
Index: context.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Context Container</title>
</properties>
<body>
<section name="Introduction">
<p>The <strong>Context</strong> element represents a <em>web
application</em>, which is run within a particular virtual host.
Each web application is based on a <em>Web Application Archive</em>
(WAR) file, or a corresponding directory containing the corresponding
unpacked contents, as described in the Servlet Specification (version
2.2 or later). For more information about web application archives,
you can download the
<a href="http://java.sun.com/products/servlet/download.html";>Servlet
Specification</a>, and review the Tomcat
<a href="../appdev/index.html">Application Developer's Guide</a>.</p>
<p>The web application used to process each HTTP request is selected
by Catalina based on matching the longest possible prefix of the
Request URI against the <em>context path</em> of each defined Context.
Once selected, that Context will select an appropriate servlet to
process the incoming request, according to the servlet mappings defined
in the <em>web application deployment descriptor</em> file (which MUST
be located at <code>/WEB-INF/web.xml</code> within the web app's
directory hierarchy).</p>
<p>You may define as many <strong>Context</strong> elements as you
wish, nested within a <a href="host.html">Host</a> element in
<code>conf/server.xml</code>. Each such Context MUST have a unique
context path, which is defined by the <code>path</code> attribute.
In addition, you MUST define a Context with a context path equal to
a zero-length string. This Context becomes the <em>default</em>
web application for this virtual host, and is used to process all
requests that do not match any other Context's context path.</p>
<p>In addition to explicitly specified Context elements, there are
several techniques by which Context elements can be created automatically
for you. See <a href="host.html#Automatic Application Deployment">
Automatic Application Deployment</a> and
<a href="host.html#User Web Applications">User Web Applications</a>
for more information.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Host</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Context</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="cookies" required="false">
<p>Set to <code>true</code> if you want cookies to be used for
session identifier communication if supported by the client (this
is the default). Set to <code>false</code> if you want to disable
the use of cookies for session identifier communication, and rely
only on URL rewriting by the application.</p>
</attribute>
<attribute name="crossContext" required="false">
<p>Set to <code>true</code> if you want calls within this application
to <code>ServletContext.getContext()</code> to successfully return a
request dispatcher for other web applications running on this virtual
host. Set to <code>false</code> (the default) in security
conscious environments, to make <code>getContext()</code> always
return <code>null</code>.</p>
</attribute>
<attribute name="docBase" required="true">
<p>The <em>Document Base</em> (also known as the <em>Context
Root</em>) directory for this web application, or the pathname
to the web application archive file (if this web application is
being executed directly from the WAR file). You may specify
an absolute pathname for this directory or WAR file, or a pathname
that is relative to the <code>appBase</code> directory of the
owning <a href="host.html">Host</a>.</p>
</attribute>
<attribute name="override" required="false">
<p>Set to <code>true</code> to have explicit settings in this
Context element override any corresponding settings in the
<a href="defaultcontext.html">DefaultContext</a> element associated
with our owning <a href="host.html">Host</a>. By default, settings
in the DefaultContext element will be used.</p>
</attribute>
<attribute name="path" required="true">
<p>The <em>context path</em> of this web application, which is
matched against the beginning of each request URI to select the
appropriate web application for processing. All of the context paths
within a particular <a href="host.html">Host</a> must be unique.
If you specify a context path of an empty string (""), you are
defining the <em>default</em> web application for this Host, which
will process all requests not assigned to other Contexts.</p>
</attribute>
<attribute name="reloadable" required="false">
<p>Set to <code>true</code> if you want Catalina to monitor classes in
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
changes, and automatically reload the web application if a change
is detected. This feature is very useful during application
development, but it requires significant runtime overhead and is
not recommended for use on deployed production applications. You
can use the <a href="../manager-howto.html">Manager</a> web
application, however, to trigger reloads of deployed applications
on demand.</p>
</attribute>
<attribute name="useNaming" required="false">
<p>Set to <code>true</code> (the default) to have Catalina enable a
JNDI <code>InitialContext</code> for this web application that is
compatible with Java2 Enterprise Edition (J2EE) platform
conventions.</p>
</attribute>
<attribute name="wrapperClass" required="false">
<p>Java class name of the <code>org.apache.catalina.Wrapper</code>
implementation class that will be used for servlets managed by this
Context. If not specified, a standard default value will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Context</strong> is
<strong>org.apache.catalina.core.StandardContext</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="debug" required="false">
<p>The level of debugging detail logged by this <strong>Engine</strong>
to the associated <a href="logger.html">Logger</a>. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).</p>
</attribute>
<attribute name="workDir" required="false">
<p>Pathname to a scratch directory to be provided by this Context
for temporary read-write use by servlets within the associated web
application. This directory will be made visible to servlets in the
web application by a servlet context attribute (of type
<code>java.io.File</code>) named
<code>javax.servlet.context.tempdir</code> as described in the
Servlet Specification. If not specified, a suitable directory
underneath <code>$CATALINA_HOME/work</code> will be provided.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Context</strong>
element:</p>
<ul>
<li><a href="loader.html"><strong>Loader</strong></a> -
Configure the web application class loader that will be used to load
servlet and bean classes for this web application. Normally, the
default configuration of the class loader will be sufficient.</li>
<li><a href="logger.html"><strong>Logger</strong></a> -
Configure a logger that will receive
and process all log messages for this <strong>Context</strong>. This
includes application messages logged via calls to
<code>ServletContext.log()</code>.</li>
<li><a href="manager.html"><strong>Manager</strong></a> -
Configure the session manager that will be used to create, destroy,
and persist HTTP sessions for this web application. Normally, the
default configuration of the session manager will be sufficient.</li>
<li><a href="realm.html"><strong>Realm</strong></a> -
Configure a realm that will allow its
database of users, and their associated roles, to be utilized solely
for this particular web application. If not specified, this web
application will utilize the Realm associated with the owning
<a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
<li><a href="resources.html"><strong>Resources</strong></a> -
Configure the resource manager that will be used to access the static
resources associated with this web application. Normally, the
default configuration of the resource manager will be sufficient.</li>
</ul>
</section>
<section name="Special Features">
<subsection name="Access Logs">
<p>When you run a web server, one of the output files normally generated
is an <em>access log</em>, which generates one line of information for
each request processed by the server, in a standard format. Catalina
includes an optional <a href="valve.html">Valve</a> implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.</p>
<p>You can ask Catalina to create an access log for all requests
processed by an <a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
<source>
<Context path="/examples" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log." suffix=".txt"
pattern="common"/>
...
</Context>
</source>
<p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
for more information on the configuration attributes that are
supported.</p>
</subsection>
<subsection name="Automatic Context Configuration">
<p>If you use the standard <strong>Context</strong> implementation,
the following configuration steps occur automtically when Catalina
is started, or whenever this web application is reloaded. No special
configuration is required to enable this feature.</p>
<ul>
<li>If you have not declared your own <a href="loader.html">Loader</a>
element, a standard web application class loader will be configured.
</li>
<li>If you have not declared your own <a href="manager.html">Manager</a>
element, a standard session manager will be configured.</li>
<li>If you have not declared your own <a href="resources.html">Resources</a>
element, a standard resources manager will be configured.</li>
<li>The web application properties listed in <code>conf/web.xml</code>
will be processed as defaults for this web application. This is used
to establish default mappings (such as mapping the <code>*.jsp</code>
extension to the corresponding JSP servlet), and other standard
features that apply to all web applications.</li>
<li>The web application properties listed in the
<code>/WEB-INF/web.xml</code> resource for this web application
will be processed (if this resource exists).</li>
<li>If your web application has specified security constraints that might
require user authentication, an appropriate Authenticator that
implements the login method you have selected will be configured.</li>
</ul>
</subsection>
<subsection name="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
<strong>Context</strong> is started or stopped, you can declare it by
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
it will be notified about the occurrence of the coresponding
lifecycle events. Configuration of such a listener looks like this:</p>
<source>
<Context path="/examples" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Context>
</source>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
</subsection>
<subsection name="Request Filters">
<p>You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.htm">Context</a> element. The remote address or name
will be checked against a configured list of "accept" and/or "deny"
filters, which are defined using the Regular Expression syntax supported
by the <a href="http://jakarta.apache.org/regexp/";>Jakarta Regexp</a>
regular expression library. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
<source>
<Context path="/examples" ...>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow="*.mycompany.com,www.yourcompany.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192.168.1.*"/>
...
</Context>
</source>
<p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/host.xml
Index: host.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Craig R. McClanahan</author>
<title>The Host Container</title>
</properties>
<body>
<section name="Introduction">
<p>The <strong>Host</strong> element represents a <em>virtual host</em>,
which is an association of a network name for a server (such as
"www.mycompany.com" with the particular server on which Catalina is
running. In order to be effective, this name must be registered in the
<em>Domain Name Service</em> (DNS) server that manages the Internet
domain you belong to - contact your Network Administrator for more
information.</p>
<p>In many cases, System Administrators wish to associate more than
one network name (such as <code>www.mycompany.com</code> and
<code>company.com</code>) with the same virtual host and applications.
This can be accomplished using the <a href="#Host Name Aliases">Host
Name Aliases</a> feature discussed below.</p>
<p>One or more <strong>Host</strong> elements are nested inside an
<a href="engine.html">Engine</a> element. Inside the Host element, you
can nest <a href="context.html">Context</a> elements for the web
applications associated with this virtual host. Exactly one of the Hosts
associated with each Engine MUST have a name matching the
<code>defaultHost</code> attribute of that Engine.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Host</strong>
support the following attributes:</p>
<attributes>
<attribute name="appBase" required="true">
<p>The <em>Application Base</em> directory for this virtual host.
This is the pathname of a directory that may contain web applications
to be deployed on this virtual host. You may specify an
absolute pathname for this directory, or a pathname that is relative
to the <code>$CATALINA_HOME</code> directory. See
<a href="#Automatic Application Deployment">Automatic Application
Deployment</a> for more information on automatic recognition and
deployment of web applications to be deployed automatically.</p>
</attribute>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Host</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="name" required="true">
<p>Network name of this virtual host, as registered in your
<em>Domain Name Service</em> server. One of the Hosts nested within
an <a href="engine.html">Engine</a> MUST have a name that matches the
<code>defaultHost</code> setting for that Engine. See
<a href="#Host Name Aliases">Host Name Aliases</a> for information
on how to assign more than one network name to the same
virtual host.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Host</strong> is
<strong>org.apache.catalina.core.StandardHost</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="debug" required="false">
<p>The level of debugging detail logged by this <strong>Engine</strong>
to the associated <a href="logger.html">Logger</a>. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).</p>
</attribute>
<attribute name="unpackWARs" required="false">
<p>Set to <code>true</code> if you want web applications that are
deployed into this virtual host from a Web Application Archive (WAR)
file to be unpacked into a disk directory structure, or
<code>false</code> to run the application directly from a WAR file.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>You can nest one or more <a href="host.html">Context</a> elements inside
this <strong>Context</strong> element, each representing a different web
application associated with this virtual host. In addition, you can nest a
single <a href="defaultcontext.html">DefaultContext</a> element that defines
default values for subsequently deployed web applications.</p>
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Host</strong>
element:</p>
<ul>
<li><a href="logger.html"><strong>Logger</strong></a> -
Configure a logger that will receive
and process all log messages for this <strong>Host</strong>, plus
messages from <a href="context.html">Contexts</a> associated with
this Host (unless overridden by a
<a href="logger.html">Logger</a> configuration at a lower level).</li>
<li><a href="realm.html"><strong>Realm</strong></a> -
Configure a realm that will allow its
database of users, and their associated roles, to be shared across all
<a href="context.html">Contexts</a> nested inside this Host (unless
overridden by a <a href="realm.html">Realm</a> configuration
at a lower level).</li>
</ul>
</section>
<section name="Special Features">
<subsection name="Access Logs">
<p>When you run a web server, one of the output files normally generated
is an <em>access log</em>, which generates one line of information for
each request processed by the server, in a standard format. Catalina
includes an optional <a href="valve.html">Valve</a> implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.</p>
<p>You can ask Catalina to create an access log for all requests
processed by an <a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
<source>
<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log." suffix=".txt"
pattern="common"/>
...
</Host>
</source>
<p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
for more information on the configuration attributes that are
supported.</p>
</subsection>
<subsection name="Automatic Application Deployment">
<p>If you are using the standard <strong>Host</strong> implementation,
the following actions take place automatically when Catalina is first
started. All processing takes place in the <em>application base
directory</em> that is configured by the <code>appBase</code> property.
No special configuration is required to enable these activities:</p>
<ul>
<li>Any web application archive file that does not have a corresponding
directory of the same name (without the ".war" extension) will be
automatically expanded, unless the <code>unpackWARs</code> property
is set to <code>false</code>. If you redeploy an updated WAR file,
be sure to delete the expanded directory when restarting Tomcat, so
that the updated WAR file will be re-expanded.</li>
<li>Any subdirectory within the <em>application base directory</em>
that appears to be an unpacked web application (that is, it contains
a <code>/WEB-INF/web.xml</code> file) will receive an automatically
generated <a href="context.html">Context</a> element, even if this
directory is not mentioned in the <code>conf/server.xml</code> file.
This generated Context entry will be configured according to the
properties set in any <a href="defaultcontext.html">DefaultContext</a>
element nested in this Host element. The context path for this
deployed Context will be a slash character ("/") followed by the
directory name, unless the directory name is ROOT, in which case
the context path will be an empty string ("").</li>
</ul>
<p>The net effect of this feature is that you need not specifically
mention your web applications in <code>conf/server.xml</code>, unless
you wish to define non-default properties for the corresponding
<a href="context.html">Context</a>.</p>
</subsection>
<subsection name="Host Name Aliases">
<p>In many server environments, Network Administrators have configured
more than one network name (in the <em>Domain Name Service</em> (DNS)
server), that resolve to the IP address of the same server. Normally,
each such network name would be configured as a separate
<strong>Host</strong> element in <code>conf/server.xml</code>, each
with its own set of web applications.</p>
<p>However, in some circumstances, it is desireable that two or more
network names should resolve to the <strong>same</strong> virtual host,
running the same set of applications. A common use case for this
scenario is a corporate web site, where it is desireable that users
be able to utilize either <code>www.mycompany.com</code> or
<code>company.com</code> to access exactly the same content and
applications.</p>
<p>This is accomplished by utilizing one or more <strong>Alias</strong>
elements nested inside your <strong>Host</strong> element. For
example:</p>
<source>
<Host name="www.mycompany.com" ...>
...
<Alias name="mycompany.com"/>
...
</Host>
</source>
<p>In order for this strategy to be effective, all of the network names
involved must be registered in your DNS server to resolve to the
same computer that is running this instance of Catalina.</p>
</subsection>
<subsection name="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
<strong>Host</strong> is started or stopped, you can declare it by
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
it will be notified about the occurrence of the coresponding
lifecycle events. Configuration of such a listener looks like this:</p>
<source>
<Host name="localhost" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Host>
</source>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
</subsection>
<subsection name="Request Filters">
<p>You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.htm">Context</a> element. The remote address or name
will be checked against a configured list of "accept" and/or "deny"
filters, which are defined using the Regular Expression syntax supported
by the <a href="http://jakarta.apache.org/regexp/";>Jakarta Regexp</a>
regular expression library. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
<source>
<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow="*.mycompany.com,www.yourcompany.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192.168.1.*"/>
...
</Host>
</source>
<p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</subsection>
<subsection name="Single Sign On">
<p>In many environments, but particularly in portal environments, it
is desireable to have a user challenged to authenticate themselves only
once over a set of web applications deployed on a particular virtual
host. This can be accomplished by nesting an element like this inside
the Host element for this virtual host:</p>
<source>
<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.authenticator.SingleSignOn"
debug="0"/>
...
</Host>
</source>
<p>The Single Sign On facility operates according to the following rules:
</p>
<ul>
<li>All web applications configured for this virtual host must share the
same <a href="realm.html">Realm</a>. In practice, that means you can
nest the Realm element inside this Host element (or the surrounding
<a href="engine.html">Engine</a> element), but not inside a
<a href="context.html">Context</a> element for one of the involved
web applications.</li>
<li>As long as the user accesses only unprotected resources in any of the
web applications on this virtual host, they will not be challenged
to authenticate themselves.</li>
<li>As soon as the user accesses a protected resource in
<strong>any</strong> web application associated with this virtual
host, the user will be challenged to authenticate himself or herself,
using the login method defined for the web application currently
being accessed.</li>
<li>Once authenticated, the roles associated with this user will be
utilized for access control decisions across <strong>all</strong>
of the associated web applications, without challenging the user
to authenticate themselves to each application individually.</li>
<li>As soon as the user logs out of one web application (for example,
by invalidating or timing out the corresponding session if form
based login is used), the user's sessions in <strong>all</strong>
web applications will be invalidated. Any subsequent attempt to
access a protected resource in any application will require the
user to authenticate himself or herself again.</li>
<li>The Single Sign On feature utilizes HTTP cookies to transmit a token
that associates each request with the saved user identity, so it can
only be utilized in client environments that support cookies.</li>
</ul>
</subsection>
<subsection name="User Web Applications">
<p>Many web servers can automatically map a request URI starting with
a tilde character ("~") and a username to a directory (commonly named
<code>public_html</code>) in that user's home directory on the server.
You can accomplish the same thing in Catalina by using a special
<strong>Listener</strong> element like this (on a Unix system that
uses the <code>/etc/passwd</code> file to identify valid users):</p>
<source>
<Host name="localhost" ...>
...
<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
...
</Host>
</source>
<p>On a server where <code>/etc/passwd</code> is not in use, you can
request Catalina to consider all directories found in a specified base
directory (such as <code>c:\Homes</code> in this example) to be
considered "user home" directories for the purposes of this directive:</p>
<source>
<Host name="localhost" ...>
...
<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
homeBase=c:\Homes"
userClass="org.apache.catalina.startup.HomesUserDatabase"/>
...
</Host>
</source>
<p>If a user home directory has been set up for a user named
<code>craigmcc</code>, then its contents will be visible from a
client browser by making a request to a URL like:</p>
<source>
http://www.mycompany.com:8080/~craigmcc
</source>
<p>Successful use of this feature requires recognition of the following
considerations:</p>
<ul>
<li>Each user web application will be deployed with characteristics
established by any <a href="defaultcontext.html">DefaultContext</a>
element you have configured for this Host.</li>
<li>It is legal to include more than one instance of this Listener
element. This would only be useful, however, in circumstances
where you wanted to configure more than one "homeBase" directory.</li>
<li>The operating system username under which Catalina is executed
MUST have read access to each user's web application directory,
and all of its contents.</li>
</ul>
</subsection>
</section>
</body>
</document>
