The Engine Component

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

Introduction

An Engine component represents the entire Catalina servlet container. A single instance of an Engine component is configured for each Service, to receive all requests received by one or more Connector components. This element must be nested immediately after the Connector elements, inside the owning Service element.

Request processing Valves that are nested here will be executed for every request received from every Connector configured within this service.

Common Attributes

All implementations of the Engine component support the following attributes:

Attribute	Description
`className`	Java class name of the implementation to use. This class must implement the `org.apache.catalina.Engine` interface. If no class name is specified, the standard implementation will be used (`org.apache.catalina.core.StandardEngine`).
`defaultHost`	The default host name, identifying the Host to which requests from unidentified remote hosts will be directed.
`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 also supports the following attributes:

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).

Utility Components

You can attach one or more of the following utility components by nesting a corresponding declaration inside your Engine element. Unless overridden by a utility component of the same name being nested in a Host or Context element, the utility components you declare here will be shared among all virtual hosts and web applications running in this Engine:

Logger - Configure a logger that will receive all log messages from this Engine, plus log messages from Connectors attached to this Engine. In addition, this Logger will log messages from subordinate Hosts and Contexts, unless overridden by a Logger configuration at a lower level.
Realm - Configure a realm that will allow your database of users, and their associated roles, to be shared across all of the Hosts, and all web applications running within these Hosts.

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.catalina.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.catalina.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>

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. Example filter declarations:


    <Engine name="engine" ...>
      ...
      <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>

See Remote Address Filter or Remote Host Filter for more information on the syntax of these filters, and the logic that is applied when they are executed.