The Engine Component


[Introduction] [Common Attributes] [Standard Implementation Attributes] [Utility Components] [Special Features]

Introduction

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.


Common Attributes

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.

Standard Implementation Attributes

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.

Utility Components

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:


Special Features

Access Logs

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.

Lifecycle Listeners

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.

Request Filters

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.