How tomcat works——13 Host 和 Engine

概述

本章要讨论的2个主题是主机（host）和引擎（Engine）。如果需要在一个 Tomcat部署中部署多个上下文，需要使用一个主机。理论上，当只有一个上下文容器时不需要主机，正如下面 org.apache.catalina.Context 接口中描述：

“上下文容器的父容器通常是主机，但是可能有一些其它实现，没有必要的时候也可以忽略”

然而在实践中，一个 Tomcat 部署往往需要一个主机。至于为什么，将会在本章后面的“为什么需要Host” 一节中看到。

Engine表示整个 Catalina 的 Servlet 引擎。如果使用的话，它通常位于容器等级的最高层。可以添加到Engine上的子容器通常实现于org.apache.catalina.Host 或org.apache.catalina.Context。在一个 Tomcat 部署中，默认是使用引擎容器的。在该部署中，Engine有一个Host，默认主机。

本章讨论了跟 Host 和 Engine 接口相关的类。首先介绍了 Host 相关的StandardHost、StandardHostMapper（Tomcat4）以及 StandardHostValve 类。接下来是用一个Demo来示范演示了Host作为顶层容器的情况。Engine是本章讨论的第二个主题，介绍了StandardEngine和StandardEngineValve类。接下来是本章的第2个应用Demo，说明了如何将Engine作为顶层容器使用。

13.1 Host接口

主机是用 org.apache.catalina.Host 接口表示的。本接口继承了 Container 接口，如 Listing13.1 所示：

Listing 13.1: The Host interface

package org.apache.catalina;

public interface Host extends Container {


    // ----------------------------------------------------- Manifest Constants


    /**
     * The ContainerEvent event type sent when a new alias is added
     * by <code>addAlias()</code>.
     */
    public static final String ADD_ALIAS_EVENT = "addAlias";


    /**
     * The ContainerEvent event type sent when an old alias is removed
     * by <code>removeAlias()</code>.
     */
    public static final String REMOVE_ALIAS_EVENT = "removeAlias";


    // ------------------------------------------------------------- Properties


    /**
     * Return the application root for this Host.  This can be an absolute
     * pathname, a relative pathname, or a URL.
     */
    public String getAppBase();


    /**
     * Set the application root for this Host.  This can be an absolute
     * pathname, a relative pathname, or a URL.
     *
     * @param appBase The new application root
     */
    public void setAppBase(String appBase);


    /**
     * Return the value of the auto deploy flag.  If true, it indicates that 
     * this host's child webapps should be discovred and automatically 
     * deployed.
     */
    public boolean getAutoDeploy();


    /**
     * Set the auto deploy flag value for this host.
     * 
     * @param autoDeploy The new auto deploy flag
     */
    public void setAutoDeploy(boolean autoDeploy);


    /**
     * Set the DefaultContext
     * for new web applications.
     *
     * @param defaultContext The new DefaultContext
     */
    public void addDefaultContext(DefaultContext defaultContext);


    /**
     * Retrieve the DefaultContext for new web applications.
     */
    public DefaultContext getDefaultContext();


    /**
     * Return the canonical, fully qualified, name of the virtual host
     * this Container represents.
     */
    public String getName();


    /**
     * Set the canonical, fully qualified, name of the virtual host
     * this Container represents.
     *
     * @param name Virtual host name
     *
     * @exception IllegalArgumentException if name is null
     */
    public void setName(String name);


    // --------------------------------------------------------- Public Methods


    /**
     * Import the DefaultContext config into a web application context.
     *
     * @param context web application context to import default context
     */
    public void importDefaultContext(Context context);


    /**
     * Add an alias name that should be mapped to this same Host.
     *
     * @param alias The alias to be added
     */
    public void addAlias(String alias);


    /**
     * Return the set of alias names for this Host.  If none are defined,
     * a zero length array is returned.
     */
    public String[] findAliases();


    /**
     * Return the Context that would be used to process the specified
     * host-relative request URI, if any; otherwise return <code>null</code>.
     *
     * @param uri Request URI to be mapped
     */
    public Context map(String uri);


    /**
     * Remove the specified alias name from the aliases for this Host.
     *
     * @param alias Alias name to be removed
     */
    public void removeAlias(String alias);


}

特别重要的是map ()方法，它返回合适的上下文来处理请求，该方法的实现可以在StandardHost 类中找到，将在下一小节中讨论。

13.2 StandardHost类

org.apache.catalina.core.StandardHost 类是对 Host 接口的标准实现。该类继承了 org.apache.catalina.core.ContainerBase 类并实现了 Host和Deployer 接口。Deployer 接口将在第 17 章讨论。

跟 StandardContext 和 StandardWrapper 类相似，StandardHost 类的构造函数在它的管道中添加一基础阀门：

public StandardHost() {
    super();
    pipeline.setBasic(new StandardHostValve());
}

如你所见，该基础阀门类型为 org.apache.catalina.core.StandardHostValve。

当启动时，如 start()方法被调用时，StandardHost 上面添加2个阀门：ErrorReportValve 和 ErrorDispatcherValve。它们都在org.apache.catalina.valves 包中。Tomcat4 中 StandardHost 的 start()方法如Listing13.2 所示：

Listing 13.2: The start method of StandardHost

public synchronized void start() throws LifecycleException {
    // Set error report valve
    if ((errorReportValveClass != null)&& (!errorReportValveClass.equals(""))) {
        try {
            Valve valve =(Valve) Class.forName(errorReportValveClass).newInstance();
            addValve(valve);
        }catch (Throwable t) {
            log(sm.getString("StandardHost.invalidErrorReportValveClass",
                errorReportValveClass));
        }
    }
    // Set dispatcher valve
    addValve(new ErrorDispatcherValve());
    super.start();
}

注意：在 Tomcat5 中，start()方法相似，不同点在于包括了构建 JMX 对象的代码，JMX 将在第 20 章讨论。

errorReportValveClass 的值定义如下：

private String errorReportValveClass ="org.apache.catalina.valves.ErrorReportValve";

对于每一个请求，都会调用主机的 invoke()方法。由于 StanardHost 类并没有实现invoke()方法，所以会调用它的父类ContainerBase类的invoke()方法。该invoke()方法会转而调用 StandardHost 的基础阀门 StandardHostValve 的 invoke() 方法。StandardHostValve 阀门的 invoke()方法将在 “StandardHostValve类”小节中讨论。特别是StandardHostValve 的 invoke()方法调用 StandardHost 类的 map()方法来获得一个合适的上下文容器进行请求处理。StandardHost 的 map()方法如 Listing13.3 所示：

Listing 13.3: The map method in the StandardHost class

public Context map(String uri) {

        if (debug > 0)
            log("Mapping request URI '" + uri + "'");
        if (uri == null)
            return (null);

        // Match on the longest possible context path prefix
        if (debug > 1)
            log("  Trying the longest context path prefix");
        Context context = null;
        String mapuri = uri;
        while (true) {
            context = (Context) findChild(mapuri);
            if (context != null)
                break;
            int slash = mapuri.lastIndexOf('/');
            if (slash < 0)
                break;
            mapuri = mapuri.substring(0, slash);
        }

        // If no Context matches, select the default Context
        if (context == null) {
            if (debug > 1)
                log("  Trying the default context");
            context = (Context) findChild("");
        }

        // Complain if no Context has been selected
        if (context == null) {
            log(sm.getString("standardHost.mappingError", uri));
            return (null);
        }

        // Return the mapped Context (if any)
        if (debug > 0)
            log(" Mapped to context '" + context.getPath() + "'");
        return (context);

    }

注意在 Tomcat4 中，ContainerBase 类也声明了一个 map()方法如下签名：

public Container map(Request request, boolean update);

在 Tomcat4 中，StandardHostVavle 的 invoke()方法调用 ContainerBase 的 map()方法，它转而调用 StandardHost 的 map()方法。在 Tomcat5 中，没有映射器组件，适当的上下文将从请求对象中获得。

13.3 StandardHostMapper类

在 Tomcat4 中，StandardHost 的父类 ContainerBase 在start()方法中调用 addDefaultMapper()方法创建一个默认映射器。默认映射器的类型由 mapperClass 属性指定。如下是ContainerBase 的 addDefaulstMapper()方法：

protected void addDefaultMapper(String mapperClass) {
    // Do we need a default Mapper?
    if (mapperClass == null)
        return;
    if (mappers.size() >= 1)
        return;
    // Instantiate and add a default Mapper
    try {
        Class clazz = Class.forName(mapperClass);
        Mapper mapper = (Mapper) clazz.newInstance();
        mapper.setProtocol("http");
        addMapper(mapper);
    }catch (Exception e) {
        log(sm.getString("containerBase.addDefaultMapper", mapperClass),e);
    }
}

StandardHost 定义 mapperClass 变量如下：

private String mapperClass = "org.apache.catalina.core.StandardHostMapper";

另外，StandardHost 类的 start()方法在它的最后调用super.start()来保证创建一个默认的映射器。

注意：Tomcat4 中的 standardContext 使用了略微不同的方法来创建一个默认映射器。它的 start() 方法中并没有调用 super.start()。相反 StandardContext 的start()方法调用 addDefaultMapper()来传递 mapperClass 变量。

StandardHostMapper 中最重要的是 map()方法，下面是它的实现：

public Container map(Request request, boolean update) {
    // Has this request already been mapped?
    if (update && (request.getContext() != null))
        return (request.getContext());
    // Perform mapping on our request URI
    String uri = ((HttpRequest) request).getDecodedRequestURI();
    Context context = host.map(uri);
    // Update the request (if requested) and return the selected Context
    if (update) {
        request.setContext(context);
    if (context != null)
        ((HttpRequest) request).setContextPath(context.getPath());
    else
        ((HttpRequest) request).setContextPath(null);
    }
    return (context);
}

注意，map() 方法仅仅是简单地调用了 Host 的 map()方法。

13.4 StandardHostValve类

org.apache.catalina.core.StandardHostValve 类是 StandardHost 的基础阀门。当有 HTTP 请求时会调用它的 invoke()方法，代码如Listing 13.4：

Listing 13.4: The invoke method of StandardHostValve

public void invoke(Request request, Response response,
                       ValveContext valveContext)
        throws IOException, ServletException {

        // Validate the request and response object types
        if (!(request.getRequest() instanceof HttpServletRequest) ||
            !(response.getResponse() instanceof HttpServletResponse)) {
            return;     // NOTE - Not much else we can do generically
        }

        // Select the Context to be used for this Request
        StandardHost host = (StandardHost) getContainer();
        Context context = (Context) host.map(request, true);
        if (context == null) {
            ((HttpServletResponse) response.getResponse()).sendError
                (HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
                 sm.getString("standardHost.noContext"));
            return;
        }

        // Bind the context CL to the current thread
        Thread.currentThread().setContextClassLoader
            (context.getLoader().getClassLoader());

        // Update the session last access time for our session (if any)
        HttpServletRequest hreq = (HttpServletRequest) request.getRequest();
        String sessionId = hreq.getRequestedSessionId();
        if (sessionId != null) {
            Manager manager = context.getManager();
            if (manager != null) {
                Session session = manager.findSession(sessionId);
                if ((session != null) && session.isValid())
                    session.access();
            }
        }

        // Ask this Context to process this request
        context.invoke(request, response);

    }

在 Tomcat4 中invoke()方法中调用 StandardHost 的map()方法来获得一个合适的上下文：

// Select the Context to be used for this Request
StandardHost host = (StandardHost) getContainer();
Context context = (Context) host.map(request, true);

注意：在得到上下对象的时候需要一个往返过程。map() 方法接收2个参数，该方法是在 ContainerBase 中的。然后 ContainerBase 类又在它的子对象(这里是StandardHost对象)中查找合适的映射器并调用它的 map()方法。

invoke()方法解析得到一个 Session 对象并调用它的 access()方法更新它的最后进入访问时间。如下是org.apache.catalina.session.StandardSession 类中的 access() 方法实现：

public void access() {
    this.isNew = false;
    this.lastAccessedTime = this.thisAccessedTime;
    this.thisAccessedTime = System.currentTimeMillis();
}

最后，invoke()方法调用上下文容器的 invoke()方法，让上下文来处理请求。

13.5为什么需要Host

一Tomcat 部署必须有一个Host，如果该Context使用 ContextConfig 来配置。原因如下：

ContextConfig 需要应用文件 web.xml 的位置，它在applicationConfig()方法中尝试打开该文件，下面是该方法的片段：

synchronized (webDigester) {
    try {
        URL url =
        servletContext.getResource(Constants.ApplicationWebXml);
        InputSource is = new InputSource(url.toExternalForm());
        is.setByteStream(stream);
        ...
        webDigester.parse(is);
        ...

Constants.ApplicationWebXml 定义的是 /WEB-INF/web.xml文件的相对地址，servletContext是一个 org.apache.catalina.core.ApplicationContext 类型的对象（它实现了javax.servlet.ServletContext）。

下面是 ApplicationContext 类中的 getResource()方法：

public URL getResource(String path)throws MalformedURLException {
    DirContext resources = context.getResources();
    if (resources != null) {
        String fullPath = context.getName() + path;
        // this is the problem. Host must not be null
        String hostName = context.getParent().getName();

最后一行清楚表明context的父容器（host）是必须的，如果使用 ContextConfig来配置的话。在第 15 章中将会介绍如何解析 web.xml 文件。简单的说，除非自己写 ContextConfig 类，否则你必须有一个主机。

13.6 应用Demo1

本章第一个应用Demo演示了如何将一个主机作为顶层容器使用。该程序有2个类组成：ex13.pyrmont.core.SimpleContextConfig 和ex13.pyrmont.startup.Bootstrap1 类。SimpleContextConfig 类跟第 11 章中的相同，Boostrap2 类如 Listing13.5 所示：

Listing 13.5: The Bootstrap1 Class

package ex13.pyrmont.startup;

//explain Host
import ex13.pyrmont.core.SimpleContextConfig;
import org.apache.catalina.Connector;
import org.apache.catalina.Context;
import org.apache.catalina.Host;
import org.apache.catalina.Lifecycle;
import org.apache.catalina.LifecycleListener;
import org.apache.catalina.Loader;
import org.apache.catalina.Wrapper;
import org.apache.catalina.connector.http.HttpConnector;
import org.apache.catalina.core.StandardContext;
import org.apache.catalina.core.StandardHost;
import org.apache.catalina.core.StandardWrapper;
import org.apache.catalina.loader.WebappLoader;


public final class Bootstrap1 {
  public static void main(String[] args) {
    //invoke: http://localhost:8080/app1/Primitive or http://localhost:8080/app1/Modern
    System.setProperty("catalina.base", System.getProperty("user.dir"));
    Connector connector = new HttpConnector();

    Wrapper wrapper1 = new StandardWrapper();
    wrapper1.setName("Primitive");
    wrapper1.setServletClass("PrimitiveServlet");
    Wrapper wrapper2 = new StandardWrapper();
    wrapper2.setName("Modern");
    wrapper2.setServletClass("ModernServlet");

    Context context = new StandardContext();
    // StandardContext's start method adds a default mapper
    context.setPath("/app1");
    context.setDocBase("app1");

    context.addChild(wrapper1);
    context.addChild(wrapper2);

    LifecycleListener listener = new SimpleContextConfig();
    ((Lifecycle) context).addLifecycleListener(listener);

    Host host = new StandardHost();
    host.addChild(context);
    host.setName("localhost");
    host.setAppBase("webapps");

    Loader loader = new WebappLoader();
    context.setLoader(loader);
    // context.addServletMapping(pattern, name);
    context.addServletMapping("/Primitive", "Primitive");
    context.addServletMapping("/Modern", "Modern");

    connector.setContainer(host);
    try {
      connector.initialize();
      ((Lifecycle) connector).start();
      ((Lifecycle) host).start();

      // make the application wait until we press a key.
      System.in.read();
      ((Lifecycle) host).stop();
    }
    catch (Exception e) {
      e.printStackTrace();
    }
  }
}

13.6.1 运行Demo

在 Windows 下面可以在工作目录下输入如下命令运行该程序：

java -classpath ./lib/servlet.jar;./lib/commons-collections.jar;./lib/commons—digester.jar;./
ex13.pyrmont.startup.Bootstrap1

在 Linux 下面需要使用分号来分隔开两个库

java -classpath ./lib/servlet.jar:./lib/commons-collections.jar:./lib/commons-digester.jar:./
ex13.pyrmont.startup.Bootstrap1

使用如下 URL 可以调用 PrimitiveServlet和ModernServlet：

http://localhost:8080/app1/Primitive
http://localhost:8080/app1/Modern

13.7 Engine接口

org.apache.catalina.Engine 接口用来表示一个引擎。Engine表示整个 Catalina的 Servlet 引擎。当我们想要支持多个虚拟主机时，需要一个引擎，实际上Tomcat 部署正是使用了引擎。Engine 接口如 Listing 13.6 所示：

Listing 13.6: The Engine Interface

public interface Engine extends Container {


    // ------------------------------------------------------------- Properties


    /**
     * Return the default hostname for this Engine.
     */
    public String getDefaultHost();


    /**
     * Set the default hostname for this Engine.
     *
     * @param defaultHost The new default host
     */
    public void setDefaultHost(String defaultHost);


    /**
     * Retrieve the JvmRouteId for this engine.
     */
    public String getJvmRoute();


    /**
     * Set the JvmRouteId for this engine.
     *
     * @param jvmRouteId the (new) JVM Route ID. Each Engine within a cluster
     *        must have a unique JVM Route ID.
     */
    public void setJvmRoute(String jvmRouteId);


    /**
     * Return the <code>Service</code> with which we are associated (if any).
     */
    public Service getService();


    /**
     * Set the <code>Service</code> with which we are associated (if any).
     *
     * @param service The service that owns this Engine
     */
    public void setService(Service service);


    /**
     * Set the DefaultContext
     * for new web applications.
     *
     * @param defaultContext The new DefaultContext
     */
    public void addDefaultContext(DefaultContext defaultContext);


    /**
     * Retrieve the DefaultContext for new web applications.
     */
    public DefaultContext getDefaultContext();


    // --------------------------------------------------------- Public Methods


    /**
     * Import the DefaultContext config into a web application context.
     *
     * @param context web application context to import default context
     */
    public void importDefaultContext(Context context);


}

可以给引擎设置默认主机或上下文。注意引擎也跟服务（service）相关联。将在第 14 章介绍Services 相关内容。

13.8 StandardEngine类

类 org.apache.catalina.core.StandardEngine 是 Engine 接口的标准实现，跟StandardContext 和 StandardHost 相比，StandardEngine 类相对较小。初始化时，StandardEngine 类需要添加一个基础阀门，下面是该类构造函数：

public StandardEngine() {
    super();
    pipeline.setBasic(new StandardEngineValve());
}

作为顶层容器，StandardEngine 可以有子容器，它的子容器必须是主机（host）。如果你尝试给它添加一个非主机容器，会产生异常。如下是StandardEngine 类的 addChile()方法：

public void addChild(Container child) {
    if (!(child instanceof Host))
        throw new IllegalArgumentException(sm.getString("StandardEngine.notHost"));
    super.addChild(child);
}

由于位于容器顶层，所以引擎不能有父容器，当你尝试给引擎设置父容器时会产生异常，下面是 StandardEngine 类的 setParent()方法：

public void setParent(Container container) {
    throw new IllegalArgumentException(sm.getString("standardEngine.notParent"));
}

13.9 StandardEngineValve类

org.apache.catalina.core.StandardEngineValve 是StandardEngine 的基础阀门，它的 invoke() 方法如 Listing13.7。

Listing 13.7: The invoke method of StandardEngineValve

public void invoke(Request request, Response response,
                       ValveContext valveContext)
        throws IOException, ServletException {
        // Validate the request and response object types
        if (!(request.getRequest() instanceof HttpServletRequest) ||
            !(response.getResponse() instanceof HttpServletResponse)) {
            return;     // NOTE - Not much else we can do generically
        }

        // Validate that any HTTP/1.1 request included a host header
        HttpServletRequest hrequest = (HttpServletRequest) request;
        if ("HTTP/1.1".equals(hrequest.getProtocol()) &&
            (hrequest.getServerName() == null)) {
            ((HttpServletResponse) response.getResponse()).sendError
                (HttpServletResponse.SC_BAD_REQUEST,
                 sm.getString("standardEngine.noHostHeader",
                              request.getRequest().getServerName()));
            return;
        }

        // Select the Host to be used for this Request
        StandardEngine engine = (StandardEngine) getContainer();
        Host host = (Host) engine.map(request, true);
        if (host == null) {
            ((HttpServletResponse) response.getResponse()).sendError
                (HttpServletResponse.SC_BAD_REQUEST,
                 sm.getString("standardEngine.noHost",
                              request.getRequest().getServerName()));
            return;
        }

        // Ask this Host to process this request
        host.invoke(request, response);

    }

在验证了请求对象和响应对象之后，invoke()方法获得一个 Host 实例来处理请求。是通过调用引擎的 map()方法得到主机。一旦获得了一个主机，它的 invoke()方法将会被调用。

13.10 应用Demo2

本章的第二个应用Demo用于演示引擎作为顶层容器。该Demo使用了2个类，ex13.pyrmont.core.SimpleContextConfig 和ex13.pyrmont.startup.Bootstrap2 类。Bootstrap2 类如 Listing13.8 所示。

Listing 13.8: The Bootstrap2 class

package ex13.pyrmont.startup;

//Use engine
import ex13.pyrmont.core.SimpleContextConfig;
import org.apache.catalina.Connector;
import org.apache.catalina.Context;
import org.apache.catalina.Engine;
import org.apache.catalina.Host;
import org.apache.catalina.Lifecycle;
import org.apache.catalina.LifecycleListener;
import org.apache.catalina.Loader;
import org.apache.catalina.Wrapper;
import org.apache.catalina.connector.http.HttpConnector;
import org.apache.catalina.core.StandardContext;
import org.apache.catalina.core.StandardEngine;
import org.apache.catalina.core.StandardHost;
import org.apache.catalina.core.StandardWrapper;
import org.apache.catalina.loader.WebappLoader;


public final class Bootstrap2 {
  public static void main(String[] args) {
    //invoke: http://localhost:8080/app1/Primitive or http://localhost:8080/app1/Modern
    System.setProperty("catalina.base", System.getProperty("user.dir"));
    Connector connector = new HttpConnector();

    Wrapper wrapper1 = new StandardWrapper();
    wrapper1.setName("Primitive");
    wrapper1.setServletClass("PrimitiveServlet");
    Wrapper wrapper2 = new StandardWrapper();
    wrapper2.setName("Modern");
    wrapper2.setServletClass("ModernServlet");

    Context context = new StandardContext();
    // StandardContext's start method adds a default mapper
    context.setPath("/app1");
    context.setDocBase("app1");

    context.addChild(wrapper1);
    context.addChild(wrapper2);

    LifecycleListener listener = new SimpleContextConfig();
    ((Lifecycle) context).addLifecycleListener(listener);

    Host host = new StandardHost();
    host.addChild(context);
    host.setName("localhost");
    host.setAppBase("webapps");

    Loader loader = new WebappLoader();
    context.setLoader(loader);
    // context.addServletMapping(pattern, name);
    context.addServletMapping("/Primitive", "Primitive");
    context.addServletMapping("/Modern", "Modern");

    Engine engine = new StandardEngine();
    engine.addChild(host);
    engine.setDefaultHost("localhost");

    connector.setContainer(engine);
    try {
      connector.initialize();
      ((Lifecycle) connector).start();
      ((Lifecycle) engine).start();

      // make the application wait until we press a key.
      System.in.read();
      ((Lifecycle) engine).stop();
    }
    catch (Exception e) {
      e.printStackTrace();
    }
  }
}

13.10.1 运行Demo

在 Windows 下面可以在工作目录下输入如下命令运行该程序：

java -classpath ./lib/servlet.jar;./lib/commons-collections.jar;./lib/commons—digester.jar;./
ex13.pyrmont.startup.Bootstrap2

在 Linux 下面需要使用分号来分隔开两个库

java -classpath ./lib/servlet.jar:./lib/commons-collections.jar:./lib/commons-digester.jar:./
ex13.pyrmont.startup.Bootstrap2

使用如下 URL 可以调用 PrimitiveServlet和ModernServlet：

http://localhost:8080/app1/Primitive
http://localhost:8080/app1/Modern

13.11小结

在本章中，我们讨论了两种类型的容器：主机（Host）和引擎（Engine）。本章还介绍了这两种容器的相关类。并且用2个Demo演示了如何让这两种容器作为顶层容器来工作。