Links Top Level Elements Executors Connectors Containers Nested Components Cluster Elements web.xml Other | The Engine Container| Introduction |
The Engine element represents the entire request
processing machinery associated with a particular Catalina
Service. It receives and processes
all requests from one or more Connectors,
and returns the completed response to the Connector for ultimate
transmission back to the client.
Exactly one Engine element MUST be nested inside
a Service element, following all of the
corresponding Connector elements associated with this Service.
|
| Attributes |
| Common Attributes |
All implementations of Engine
support the following attributes:
| Attribute | Description |
|---|
backgroundProcessorDelay |
This value represents the delay in seconds between the
invocation of the backgroundProcess method on this engine and
its child containers, including all hosts and contexts.
Child containers will not be invoked if their delay value is not
negative (which would mean they are using their own processing
thread). Setting this to a positive value will cause
a thread to be spawn. After waiting the specified amount of time,
the thread will invoke the backgroundProcess method on this engine
and all its child containers. If not specified, the default value for
this attribute is 10, which represent a 10 seconds delay.
| className |
Java class name of the implementation to use. This class must
implement the org.apache.catalina.Engine interface.
If not specified, the standard value (defined below) will be used.
| defaultHost |
The default host name, which identifies the
Host 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 name
attributes of one of the Host elements
nested immediately inside.
| jvmRoute |
Identifier which must be used in load balancing scenarios to enable
session affinity. The identifier, which must be unique across all
Tomcat servers which participate in the cluster, will be appended to
the generated session identifier, therefore allowing the front end
proxy to always forward a particular session to the same Tomcat
instance.
Note that the jvmRoute can also be set using the
jvmRoute system property. The jvmRoute
set in an <Engine> attribute will override
any jvmRoute system property.
| name |
Logical name of this Engine, used in log and error messages. When
using multiple Service elements in the same
Server, each Engine MUST be assigned a unique
name.
| startStopThreads |
The number of threads this Engine will use to start
child Host elements in parallel. The special
value of 0 will result in the value of
Runtime.getRuntime().availableProcessors() being used.
Negative values will result in
Runtime.getRuntime().availableProcessors() + value being
used unless this is less than 1 in which case 1 thread will be used. If
not specified, the default value of 1 will be used.
|
|
| Standard Implementation |
The standard implementation of Engine is
org.apache.catalina.core.StandardEngine.
It supports the following additional attributes (in addition to the
common attributes listed above):
|
|
| Nested Components |
You can nest one or more Host elements inside
this Engine element, each representing a different virtual
host associated with this server. At least one Host
is required, and one of the nested Hosts MUST
have a name that matches the name specified for the
defaultHost attribute, listed above.
You can nest at most one instance of the following utility components
by nesting a corresponding element inside your Engine
element:
- Realm -
Configure a realm that will allow its
database of users, and their associated roles, to be shared across all
Hosts and Contexts
nested inside this Engine, unless overridden by a
Realm configuration at a lower level.
|
| Special Features |
| Logging |
An engine is associated with the
org.apache.catalina.core.ContainerBase.[enginename]
log category. Note that the brackets are actually part of the name,
don't omit them.
|
| 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 for
each request processed by the server, in a standard format. Catalina
includes an optional Valve implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.
You can ask Catalina to create an access log for all requests
processed by an Engine,
Host, or Context
by nesting a Valve element like this:
<Engine name="Standalone" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="catalina_access_log." suffix=".txt"
pattern="common"/>
...
</Engine>
See Access Logging Valves
for more information on the configuration attributes 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 this element. The
class name you specify must implement the
org.apache.catalina.LifecycleListener interface, and
it will be notified about the occurrence of the corresponding
lifecycle events. Configuration of such a listener looks like this:
<Engine name="Standalone" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Engine>
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.
|
| Request Filters |
You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
Engine, Host, or
Context element. The remote address or name
will be checked against configured "accept" and/or "deny"
filters, which are defined using java.util.regex Regular
Expression syntax. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:
<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\.\d+"/>
...
</Engine>
See Remote Address Filter
and Remote Host Filter for
more information about the configuration options that are supported.
|
|
|
