craigmcc 01/08/24 18:14:13
Modified: webapps/tomcat-docs/config http11.xml project.xml server.xml
service.xml warp.xml
Added: webapps/tomcat-docs/config engine.xml
Log:
Add docs for <Engine> element, and tweak the existing ones slightly.
Revision Changes Path
1.2 +1 -1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/http11.xml
Index: http11.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/http11.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- http11.xml 2001/08/21 02:28:21 1.1
+++ http11.xml 2001/08/25 01:14:13 1.2
@@ -195,7 +195,7 @@
</section>
-<section name="Nested Elements">
+<section name="Nested Components">
<p>The only element that may be embedded inside a <strong>Connector</strong>
element is a <strong>Factory</strong> element, which is used to configure
1.3 +1 -1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- project.xml 2001/08/05 03:42:28 1.2
+++ project.xml 2001/08/25 01:14:13 1.3
@@ -32,7 +32,7 @@
<item name="Host" href="host.html"/>
</menu>
- <menu name="Nested Elements">
+ <menu name="Nested Components">
<item name="Default Context" href="defaultcontext.html"/>
<item name="Loader" href="loader.html"/>
<item name="Logger" href="logger.html"/>
1.2 +2 -2 jakarta-tomcat-4.0/webapps/tomcat-docs/config/server.xml
Index: server.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/server.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- server.xml 2001/08/21 02:28:21 1.1
+++ server.xml 2001/08/25 01:14:13 1.2
@@ -65,9 +65,9 @@
</section>
-<section name="Nested Elements">
+<section name="Nested Components">
- <p>No nested elements may be embedded inside a <strong>Server</strong>,
+ <p>No nested components may be embedded inside a <strong>Server</strong>,
element, except for one or more <a href="service.html">Service</a> elements.
</p>
1.2 +2 -2 jakarta-tomcat-4.0/webapps/tomcat-docs/config/service.xml
Index: service.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/service.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- service.xml 2001/08/21 02:28:21 1.1
+++ service.xml 2001/08/25 01:14:13 1.2
@@ -64,9 +64,9 @@
</section>
-<section name="Nested Elements">
+<section name="Nested Components">
- <p>No nested elements may be embedded inside a <strong>Server</strong>,
+ <p>No nested components may be embedded inside a <strong>Server</strong>,
element, except for one or more <strong>Connector</strong> elements
followed by a single <a href="engine.html">Engine</a> element.
</p>
1.2 +1 -1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/warp.xml
Index: warp.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/warp.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- warp.xml 2001/08/21 02:28:21 1.1
+++ warp.xml 2001/08/25 01:14:13 1.2
@@ -106,7 +106,7 @@
</section>
-<section name="Nested Elements">
+<section name="Nested Components">
<p><strong>FIXME</strong> - Document any use of a nested <code>Factory</code>
element for communicating with <code>mod_webapp</code> over SSL.</p>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/config/engine.xml
Index: engine.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 Engine Container</title>
</properties>
<body>
<section name="Introduction">
<p>The <strong>Engine</strong> element represents the entire request
processing machinery associated with a particular Catalina
<a href="service.html">Service</a>. It receives and processes
<em>all</em> requests from one or more <strong>Connectors</strong>,
and returns the completed response to the Connector for ultimate
transmission back to the client.</p>
<p>Exactly one <strong>Engine</strong> element MUST be nested inside
a <a href="service.html">Service</a> element, following all of the
corresponding Connector elements associated with this Service.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Engine</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.Engine</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="defaultHost" required="true">
<p>The default host name, which identifies the
<a href="host.html">Host</a> that will process requests directed
to host names on this server, but which are not configured in
this configuration file. This name MUST match the <code>name</code>
attributes of one of the <a href="host.html">Host</a> elements
nested immediately inside.</p>
</attribute>
<attribute name="name" required="true">
<p>Logical name of this Engine, used in log and error messages.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Engine</strong> is
<strong>org.apache.catalina.core.StandardEngine</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>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>You can nest one or more <a href="host.html">Host</a> elements inside
this <strong>Engine</strong> element, each representing a different virtual
host associated with this server. At least one <a href="host.html">Host</a>
is required, and one of the nested <a href="host.html">Hosts</a> MUST
have a name that matches the name specified for the
<code>defaultHost</code> attribute, listed above.</p>
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Engine</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>Engine</strong>, plus
messages from <strong>Connectors</strong> associated with this Engine
in the surrounding Service. In addition, this Logger will log messages
from subordinate <a href="host.html">Hosts</a> and
<a href="context.html">Contexts</a>, 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="host.html">Hosts</a> and <a href="context.html">Contexts</a>
nested inside this Engine, 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>
<Engine name="Standalone" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="catalina_access_log." suffix=".txt"
pattern="common"/>
...
</Engine>
</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="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
<strong>Engine</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>
<Engine name="Standalone" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Engine>
</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>
<Engine name="Standalone" ...>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow="*.mycompany.com,www.yourcompany.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192.168.1.*"/>
...
</Engine>
</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>
