An Engine component represents the entire Catalina servlet
container. Normally, a single instance of an Engine component
is configured to receive all requests received by one or more
Connector components. This element will
be nested immediately after the <Connector>
elements,
inside a <Server>
element.
Request processing Valves that are specified here will be executed for every request received from every connector.
All implementations of the Engine component support the following
attributes, which are configured in an <Engine>
element:
Attribute | Description |
---|---|
className |
Java class name of the implementation to use. This class must
implement the org.apache.tomcat.Engine interface. If
no class name is specified, the standard implementation will be
used (org.apache.tomcat.core.StandardEngine ).
|
name |
The logical name of this engine. The name selected is arbitrary, but it is required. |
The standard implementation of the Engine component supports the following attributes in addition to those supported by all implementations:
Attribute | Description |
---|---|
debug |
The level of debugging detail logged by this Engine to the associated Logger, with higher numbers generating more detailed output. If not specified, the debugging detail level will be set to zero (0). |
defaultHost |
Normally, requests which specify a Host: HTTP
header are forwarded to a Host with
a matching name or alias. If a request is received with a
requested host name that is not recognized, it will be
forwarded to the Host named here. If not specified,
such requests will be returned with an HTTP error instead.
|
You can attach one or more of the following utility components by nesting a corresponding declaration element inside your Host element. Unless overridden by a utility component of the same name being nested in a Context element, the utility components you declare here will be shared among all web applications running in this Host:
When you run a web server, one of the output files normally generated is an access log, which generates one line of information, in a standard format, for each HTTP request that was received, and responded to, by the web server. Catalina includes an optional Valve implementation that can create access logs in the same standard format created by web servers, or in any custom format desired.
You can ask Catalina to create an access log for all requests to any web application for any Host, by nesting an element like this inside your Engine element:
<Engine name="engine" ...> ... <Valve className="org.apache.tomcat.valves.AccessLogValve" prefix="catalina_access_log." suffix=".txt" pattern="common"/> ... </Engine>
See Access Log Valve for more information on the configuration options that are supported.
If you have implemented a Java object that needs to know when this Engine
is started or stopped, you can declare it by nesting a
<Listener>
element inside the <Engine>
element. The class you specify in the className
attribute
of this Listener must implement the
org.apache.tomcat.LifecycleListener
interface, and it will be
notified about the occurrence of the corresponding lifecycle events.
Configuration for such a listener might look like this:
<Engine name="engine" ...> ... <Listener className="com.mycompany.MyEngineListener"/> ... </Engine>
See Listeners for more information about lifecycle listeners.
You can ask Catalina to check the IP address, or host name, of an incoming request for the entire servlet container against a list of "accept" and "deny" filters, which are defined using the Regular Expression syntax supported by the jakarta-regexp regular expression library system. Requests that come from remote locations that are not accepted will be rejected with an HTTP "Forbidden" error. An example configuration that rejects requests from any domain except "mycompany.com") would be:
<Engine name="engine" ...> ... <Valve className="org.apache.tomcat.valves.RemoteHostValve" allow="*.mycompany.com"/> ... </Engine>
See Request Filter Valve for more information on the syntax of the filters, and the logic that is applied when they are executed.