读懂tomact源码4:Engine

Engine

note

An Engine is a Container that represents the entire Catalina servlet engine. It is useful in the following types of scenarios:

• You wish to use Interceptors that see every single request processed by the entire engine.

• You wish to run Catalina in with a standalone HTTP connector, but still want support for multiple virtual hosts.

  In general, you would not use an Engine when deploying Catalina connected to a web server (such as Apache), because the Connector will have utilized the web server’s facilities to determine which Context (or perhaps even which Wrapper) should be utilized to process this request.
  The child containers attached to an Engine are generally implementations of Host (representing a virtual host) or Context (representing individual an individual servlet context), depending upon the Engine implementation.
  If used, an Engine is always the top level Container in a Catalina hierarchy. Therefore, the implementation’s setParent() method should throw IllegalArgumentException.
  这段话的意思是：
  Engine是一个完整的tomact的请求过程，在下面几点很有用：
  1、使用拦截器（Interceptors）来看整个请求过程
  2、在一个单一的connector运行的Catalina，期待来支持多个虚拟的host
  3、一般来说，你不应该使用Engine，当部署Catalina连接到网络服务器（如Apache），因为连接器将使用Web服务器的设施来确定上下文（甚至它的包装）应该用来处理这个请求。
  4、Engine的子容器通常来说，是实现Host和Context的，具体看接口的实现
  5、在Catalina的生命周期内，engine是顶层的的容器（Container）;setParent会抛出来IllegalArgumentException异常

StandardEngine

构造方法

 /**
     * Create a new StandardEngine component with the default basic Valve.
     */
    public StandardEngine() {

        super();
        pipeline.setBasic(new StandardEngineValve());
        /* Set the jmvRoute using the system property jvmRoute */
        try {
            setJvmRoute(System.getProperty("jvmRoute"));
        } catch (Exception ex) {
            log.warn(sm.getString("standardEngine.jvmRouteFail"));
        }
        // By default, the engine will hold the reloading thread
        backgroundProcessorDelay = 10;

    }

解析Server.xml时会调用，它首先设置一个基本阀门，然后设置JVMRoute，这个在cluster中会用到，然后为backgroundProcessorDelay赋初值

成员变量

 /**
     * Host name to use when no server host, or an unknown host, is specified in the request.
     */
    private String defaultHost = null;
    /**
     * The <code>Service</code> that owns this Engine, if any.
     */
    private Service service = null;

    /**
     * Allow the base dir to be specified explicitly for each engine. In time we should stop using 
     * catalina.base property -otherwise we loose some flexibility.
     */
    private String baseDir = null;

    /**
     * The JVM Route ID for this Tomcat instance. All Route ID's must be unique across the cluster.
     */
    private String jvmRouteId;

logAccess

public void logAccess(Request request, Response response, long time,
                          boolean useDefault) {

        boolean logged = false;

        if (getAccessLog() != null) {
            accessLog.log(request, response, time);
            logged = true;
        }

        if (!logged && useDefault) {
            AccessLog newDefaultAccessLog = defaultAccessLog.get();
            if (newDefaultAccessLog == null) {
                // If we reached this point, this Engine can't have an AccessLog
                // Look in the defaultHost
                Host host = (Host) findChild(getDefaultHost());
                Context context = null;
                if (host != null && host.getState().isAvailable()) {
                    newDefaultAccessLog = host.getAccessLog();

                    if (newDefaultAccessLog != null) {
                        if (defaultAccessLog.compareAndSet(null,
                                newDefaultAccessLog)) {
                            AccessLogListener l = new AccessLogListener(this,
                                    host, null);
                            l.install();
                        }
                    } else {
                        // Try the ROOT context of default host
                        context = (Context) host.findChild("");
                        if (context != null &&
                                context.getState().isAvailable()) {
                            newDefaultAccessLog = context.getAccessLog();
                            if (newDefaultAccessLog != null) {
                                if (defaultAccessLog.compareAndSet(null,
                                        newDefaultAccessLog)) {
                                    AccessLogListener l = new AccessLogListener(
                                            this, null, context);
                                    l.install();
                                }
                            }
                        }
                    }
                }

                if (newDefaultAccessLog == null) {
                    newDefaultAccessLog = new NoopAccessLog();
                    if (defaultAccessLog.compareAndSet(null,
                            newDefaultAccessLog)) {
                        AccessLogListener l = new AccessLogListener(this, host,
                                context);
                        l.install();
                    }
                }
            }

            newDefaultAccessLog.log(request, response, time);
        }
    }

engine的配置

<!-- An Engine represents the entry point (within Catalina) that processes
         every request.  The Engine implementation for Tomcat stand alone
         analyzes the HTTP headers included with the request, and passes them
         on to the appropriate Host (virtual host).
         Documentation at /docs/config/engine.html -->

    <!-- You should set jvmRoute to support load-balancing via AJP ie :
    <Engine name="Catalina" defaultHost="localhost" jvmRoute="jvm1">
    -->
        <Engine name="Catalina" defaultHost="localhost">

      <!--For clustering, please take a look at documentation at:
          /docs/cluster-howto.html  (simple how to)
          /docs/config/cluster.html (reference documentation) -->
      <!--
      <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>
      -->

      <!-- Use the LockOutRealm to prevent attempts to guess user passwords
           via a brute-force attack -->
      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <!-- This Realm uses the UserDatabase configured in the global JNDI
             resources under the key "UserDatabase".  Any edits
             that are performed against this UserDatabase are immediately
             available for use by the Realm.  -->
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase"/>
      </Realm>

      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">

        <!-- SingleSignOn valve, share authentication between web applications
             Documentation at: /docs/config/valve.html -->
        <!--
        <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
        -->

        <!-- Access log processes all example.
             Documentation at: /docs/config/valve.html
             Note: The pattern used is equivalent to using pattern="common" -->
        <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log." suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />

      </Host>
    </Engine>

name属性是引擎的逻辑名称，在日志和错误消息中会用到，在同一台服务器上有多个Service时，name必须唯一。
defaultHost指定默认主机，如果没有分配哪个主机来执行用户请求，由这个值所指定的主机来处理，这个值必须和元素中的其中一个相同。
Engine里面除了可以指定属性之外，还可以有其它组件，比如：log,listener,filter,realm等,后面会单独分析.