source: nutchez-0.1/tomcat/webapps/docs/config/engine.html @ 222

Last change on this file since 222 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 17.8 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Engine Container</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2    The Apache Tomcat Servlet/JSP Container
3  " align="right" src="../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Global Settings</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat Configuration Reference</h1><h2>The Engine Container</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/engine.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
5
6  <p>The <strong>Engine</strong> element represents the entire request
7  processing machinery associated with a particular Catalina
8  <a href="service.html">Service</a>.  It receives and processes
9  <em>all</em> requests from one or more <strong>Connectors</strong>,
10  and returns the completed response to the Connector for ultimate
11  transmission back to the client.</p>
12
13  <p>Exactly one <strong>Engine</strong> element MUST be nested inside
14  a <a href="service.html">Service</a> element, following all of the
15  corresponding Connector elements associated with this Service.</p>
16
17</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
18
19  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
20
21    <p>All implementations of <strong>Engine</strong>
22    support the following attributes:</p>
23
24    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>backgroundProcessorDelay</code></td><td valign="center" align="left">
25        <p>This value represents the delay in seconds between the
26        invocation of the backgroundProcess method on this engine and
27        its child containers, including all hosts and contexts.
28        Child containers will not be invoked if their delay value is not
29        negative (which would mean they are using their own processing
30        thread). Setting this to a positive value will cause
31        a thread to be spawn. After waiting the specified amount of time,
32        the thread will invoke the backgroundProcess method on this engine
33        and all its child containers. If not specified, the default value for
34        this attribute is 10, which represent a 10 seconds delay.</p>
35      </td></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left">
36        <p>Java class name of the implementation to use.  This class must
37        implement the <code>org.apache.catalina.Engine</code> interface.
38        If not specified, the standard value (defined below) will be used.</p>
39      </td></tr><tr><td valign="center" align="left"><strong><code>defaultHost</code></strong></td><td valign="center" align="left">
40        <p>The default host name, which identifies the
41        <a href="host.html">Host</a> that will process requests directed
42        to host names on this server, but which are not configured in
43        this configuration file.  This name MUST match the <code>name</code>
44        attributes of one of the <a href="host.html">Host</a> elements
45        nested immediately inside.</p>
46      </td></tr><tr><td valign="center" align="left"><code>jvmRoute</code></td><td valign="center" align="left">
47        <p>Identifier which must be used in load balancing scenarios to enable
48        session affinity. The identifier, which must be unique across all
49        Tomcat 6 servers which participate in the cluster, will be appended to
50        the generated session identifier, therefore allowing the front end
51        proxy to always forward a particular session to the same Tomcat 6
52        instance.</p>
53      </td></tr><tr><td valign="center" align="left"><strong><code>name</code></strong></td><td valign="center" align="left">
54        <p>Logical name of this Engine, used in log and error messages. <em>When
55        using muliple <a href="service.html">Service</a> elements in the same
56        <a href="server.html">Server</a>, each Engine MUST be assigned a unique
57        name.</em></p>
58      </td></tr></table>
59
60  </blockquote></td></tr></table>
61
62
63  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
64
65    <p>The standard implementation of <strong>Engine</strong> is
66    <strong>org.apache.catalina.core.StandardEngine</strong>.
67    It supports the following additional attributes (in addition to the
68    common attributes listed above):</p>
69
70    <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr></table>
71
72  </blockquote></td></tr></table>
73
74
75</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
76
77  <p>You can nest one or more <a href="host.html">Host</a> elements inside
78  this <strong>Engine</strong> element, each representing a different virtual
79  host associated with this server.  At least one <a href="host.html">Host</a>
80  is required, and one of the nested <a href="host.html">Hosts</a> MUST
81  have a name that matches the name specified for the
82  <code>defaultHost</code> attribute, listed above.</p>
83
84  <p>You can optional nest a <a href="defaultcontext.html">DefaultContext</a>
85  element inside this <strong>Engine</strong> element, to define the default
86  characteristics of web applications that are automatically deployed.</p>
87
88  <p>You can nest at most one instance of the following utility components
89  by nesting a corresponding element inside your <strong>Engine</strong>
90  element:</p>
91  <ul>
92  <li><a href="realm.html"><strong>Realm</strong></a> -
93      Configure a realm that will allow its
94      database of users, and their associated roles, to be shared across all
95      <a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>
96      nested inside this Engine, unless overridden by a
97      <a href="realm.html">Realm</a> configuration at a lower level.</li>
98  </ul>
99
100</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
101
102
103  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote>
104
105    <p>An engine is associated with the
106       <code>org.apache.catalina.core.ContainerBase.[enginename]</code>
107       log category.  Note that the brackets are actually part of the name,
108       don't omit them.</p>
109
110  </blockquote></td></tr></table>
111
112
113  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Access Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote>
114
115    <p>When you run a web server, one of the output files normally generated
116    is an <em>access log</em>, which generates one line of information for
117    each request processed by the server, in a standard format.  Catalina
118    includes an optional <a href="valve.html">Valve</a> implementation that
119    can create access logs in the same standard format created by web servers,
120    or in any number of custom formats.</p>
121
122    <p>You can ask Catalina to create an access log for all requests
123    processed by an <a href="engine.html">Engine</a>,
124    <a href="host.html">Host</a>, or <a href="context.html">Context</a>
125    by nesting a <a href="valve.html">Valve</a> element like this:</p>
126
127<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
128&lt;Engine name="Standalone" ...&gt;
129  ...
130  &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
131         prefix="catalina_access_log." suffix=".txt"
132         pattern="common"/&gt;
133  ...
134&lt;/Engine&gt;
135</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr></table></div>
136
137    <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
138    for more information on the configuration attributes that are
139    supported.</p>
140
141  </blockquote></td></tr></table>
142
143
144  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Lifecycle Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
145
146    <p>If you have implemented a Java object that needs to know when this
147    <strong>Engine</strong> is started or stopped, you can declare it by
148    nesting a <strong>Listener</strong> element inside this element.  The
149    class name you specify must implement the
150    <code>org.apache.catalina.LifecycleListener</code> interface, and
151    it will be notified about the occurrence of the coresponding
152    lifecycle events.  Configuration of such a listener looks like this:</p>
153
154<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
155&lt;Engine name="Standalone" ...&gt;
156  ...
157  &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
158  ...
159&lt;/Engine&gt;
160</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr></table></div>
161
162    <p>Note that a Listener can have any number of additional properties
163    that may be configured from this element.  Attribute names are matched
164    to corresponding JavaBean property names using the standard property
165    method naming patterns.</p>
166
167  </blockquote></td></tr></table>
168
169
170  <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Request Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
171
172    <p>You can ask Catalina to check the IP address, or host name, on every
173    incoming request directed to the surrounding
174    <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
175    <a href="context.html">Context</a> element.  The remote address or name
176    will be checked against a configured list of "accept" and/or "deny"
177    filters, which are defined using the Regular Expression syntax supported
178    by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
179    regular expression library.  Requests that come from locations that are
180    not accepted will be rejected with an HTTP "Forbidden" error.
181    Example filter declarations:</p>
182
183<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
184&lt;Engine name="Standalone" ...&gt;
185  ...
186  &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
187         allow="*.mycompany.com,www.yourcompany.com"/&gt;
188  &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
189         deny="192.168.1.*"/&gt;
190  ...
191&lt;/Engine&gt;
192</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../images/void.gif"></td></tr></table></div>
193
194  <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
195  and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
196  more information about the configuration options that are supported.</p>
197
198  </blockquote></td></tr></table>
199
200
201</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
202        Copyright &copy; 1999-2008, Apache Software Foundation
203        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.