Webx Framework将负责创建一组级联的Spring容器结构。Webx所创建的Spring容器完全兼容于Spring MVC所创建的容器，可被所有使用Spring框架作为基础的WEB框架所使用。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/j2ee  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd
    ">
    ...
    <listener>
        <listener-class>com.alibaba.citrus.webx.context.WebxContextLoaderListener</listener-class> ①
    </listener>
    ...
</web-app>

Webx Framework将会自动搜索/WEB-INF目录下的XML配置文件，并创建下面这种级联的spring容器。

图 3.1. 级联的Spring容器

如图所示。Webx Framework将一个WEB应用分解成多个小应用模块：app1、app2，当然名字可以任意取。

将一个大的应用分解成若干个小应用模块，并使它们的配置文件相对独立，这是一种很不错的开发实践。然而，如果你的应用确实很简单，你不希望把你的应用分成多个小应用模块，那么，你还是需要配置至少一个小应用模块（子容器）。

每个现代的WEB应用，都需要日志系统。流行的日志系统包括Log4j、Logback。

Webx Framework使用SLF4J作为它的日志框架。因此Webx Framework理论上支持所有日志系统。然而目前为止，它只包含了log4j和logback这两种日志系统的初始化模块（如有需要，可以扩充）。初始化日志系统很简单。

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/j2ee  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd
    ">
    ...
    <listener>
        <listener-class>com.alibaba.citrus.logconfig.LogConfiguratorListener</listener-class> ①
    </listener>
    ...
</web-app>

LogConfiguratorListener会根据你当前应用所依赖的日志系统（通常配置在maven project中），来自动选择合适的日志配置文件。

	注意
	有关日志系统的使用方法，另有文档详细讲述。

Webx Framework提供了一个request contexts服务。Request contexts服务利用HttpServletRequestWrapper和HttpServletResponseWrapper对request和response对象进行包装，以实现新的功能。

一个基本的request contexts的配置看起来是下面的样子：

<services:request-contexts xmlns="http://www.alibaba.com/schema/services/request-contexts">
    <basic />
    <buffered />
    <lazy-commit />
    <parser />
    <set-locale defaultLocale="zh_CN" defaultCharset="UTF-8" />
    ...
</services:request-contexts>

<services:upload sizeMax="5M" />

Request contexts所有的功能都是可配置、可扩展的 —— 它是基于SpringExt的扩展机制。

Request contexts所增加的功能对于所有的基于标准Servlet API的应用都是透明的 —— 这些应用根本不需要知道这些扩展的存在。例如，假如你在request contexts服务中配置了增强的session框架，那么所有通过标准的Servlet API取得session的应用，都将获得新功能：

HttpSession session = request.getSession();

再比如，只要你配置了upload服务，那么下面的调用将同样适用于multipart/form-data类型的请求（Servlet API本身是不支持upload表单的）：

String value = request.getParameter("myparam");

	注意
	有关Request Contexts的原理和使用方法的详情，请参阅第 6 章 Filter、Request Contexts和Pipeline。

 Request contexts中可用的功能

表 3.2. 可用的RequestContext扩展

名称	说明
<basic>	对输入、输出的数据进行安全检查，排除可能的攻击。例如：XSS过滤、CRLF换行回车过滤等。
<buffered>	对写入response中的数据进行缓存，以便于实现嵌套的页面。
<lazy-commit>	延迟提交response，用来支持基于cookie的session。
<parser>	解析用户提交的参数，无论是普通的请求，还是multipart/form-data这样的用于上传文件的请求。
<set-locale>	设置当前请求的区域（locale）、编码字符集（charset）。
<rewrite>	改写URL及参数，类似于Apache HTTPD Server中的rewrite模块。
<session>	增强的Session框架，可将session中的对象保存到cookie、数据库或其它存储中。

	注意
	有关以上所有Request Contexts的详情，请参阅第 7 章 Request Contexts功能指南和第 8 章 Request Context之Session指南。

public class LoginAction {
    @Autowired
    private HttpServletRequest request;

    @Autowired
    private HttpServletResponse response;

    @Autowired
    private HttpSession session;
    ...
}

Webx Framework赋予开发者极大的自由，来定制处理请求的流程。这种机制就是pipeline。

Pipeline的意思是管道，管道中有许多阀门（Valve），阀门可以控制水流的走向。Webx Framework中的pipeline可以控制处理请求的流程的走向。如图所示。

图 3.3. Pipeline工作原理示意

Webx Framework并没有规定管道的内容 —— 定制管道是应用开发者的自由。然而Webx Framework提供了一系列通用valves，你可以使用它们：

	注意
	有关Pipeline的原理和使用方法的详情，请参阅第 6 章 Filter、Request Contexts和Pipeline。

当应用发生异常时，Webx Framework可以处理这些异常。

Webx Framework提供了一个开关，可以让应用运行于“生产模式（Production Mode）”或是“开发模式（Development Mode）” 。

<services:webx-configuration>
    <services:productionMode>${productionMode:true}</services:productionMode> 
</services:webx-configuration>

在开发模式下，会有一系列不同于生产模式的行为。

事实上，Webx Framework提供了一套专用的内部框架，使你可以往开发模式中添加更多的开发工具。例如，创建下面的功能并非难事：

Webx Framework提供了一个接口：ProductionModeAware。Spring context中的beans，如果实现了这个接口，就可以感知当前系统的运行模式，从而根据不同的模式选择不同的行为 —— 例如：在生产模式中打开cache，在开发模式中关闭cache。

public class ModuleLoaderServiceImpl implements ProductionModeAware {  ①
    public void setProductionMode(boolean productionMode) { ②
        this.productionMode = productionMode;
    }

    @Override
    protected void init() {
        ……
        if (cacheEnabled == null) {
            cacheEnabled = productionMode; ③
        }
        ……
    }
}

当一个HTTP请求到达时，首先由WebxFrameworkFilter接手这个请求：

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/j2ee  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd
    ">
    ...
    <filter>
        <filter-name>webx</filter-name>
        <filter-class>com.alibaba.citrus.webx.servlet.WebxFrameworkFilter</filter-class> ①
        <init-param>
            <param-name>excludes</param-name>
            <param-value><!-- 需要被“排除”的URL路径，以逗号分隔，前缀!表示“包含”。例如/static, *.jpg, !/uploads/*.jpg --></param-value>  ②
        </init-param>
        <init-param>
            <param-name>passthru</param-name>
            <param-value><!-- 需要被“略过”的URL路径，以逗号分隔，前缀!表示“不要略过”。例如/myservlet, *.jsp --></param-value>  ③
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>webx</filter-name>
        <url-pattern>/*</url-pattern>  ④
    </filter-mapping>
    ...
</web-app>

为什么使用filter而不是servlet呢？传统的WEB框架的控制器一般都是用servlet实现的。原因是：

如果你的web.xml中还有一些其它的servlet mappings，为了避免和Webx的URL起冲突，你可以把这些mapping加在excludes或passthru参数里。这样，WebxFrameworkFilter就会排除或略过指定的URL。例如：

        <init-param>
            <param-name>excludes</param-name>
            <param-value>/static, *.jpg, !/uploads/*.jpg</param-value>
        </init-param>
        <init-param>
            <param-name>passthru</param-name>
            <param-value>/myservlet, *.jsp</param-value>
        </init-param>

“passthru略过”和“excludes排除”的区别在于，如果一个servlet或filter接手被webx passthru的请求时，它们还是可以访问到webx的部分服务，包括：

也就是说，对于一个被passthru的请求，webx的行为更像是一个普通的filter。而“排除”则不同，如果一个请求被“排除”，webx将会立即放弃控制，将请求交还给服务器。接手控制的servlet或filter将无法访问webx一切的服务。

下图是WebxFrameworkFilter处理一个WEB请求的过程。

图 3.8. WebxFrameworkFilter处理请求的详细过程

如图所示，WebxFrameworkFilter接到请求以后，就会调用WebxRootController。从这里开始，进入Spring的世界 —— 此后所有的对象：WebxRootController、WebxController、RequestContext、Pipeline等，全部是通过SpringExt配置在Spring Context中的。

WebxRootController对象存在于root context中，它被所有子应用所共享。它会创建RequestContext实例 —— 从而增强request、response、session的功能。接下来，WebxController对象会被调用。

WebxController对象是由每个子应用独享的，子应用app1和app2可以有不同的WebxController实现。默认的实现，会调用pipeline。

Pipeline也是由各子应用自己来配置的。假如pipeline碰到无法处理的请求，如静态页面、图片等，pipeline应当执行<exit/> valve强制退出。然后WebxRootController就会“放弃控制” —— 这意味着request将被返还给/WEB-INF/web.xml中定义的servlet、filter或者返还给servlet engine本身来处理。

WebxRootController是被所有子应用所共享的逻辑。 假如你想创建一种新的WEB框架，可以自己定义一个新的WebxRootController的实现。这个方案非常适合作为一个新Web框架的起点。

<webx-configuration xmlns="http://www.alibaba.com/schema/services">
    <components>
        <rootController class="com.myframework.MyRootController" /> 
    </components>
</webx-configuration>

WebxController是用来控制子应用的。每个子应用可以拥有不同的WebxController实现。

Webx Framework默认的WebxController是调用pipeline。假如你不想用pipeline，而希望实现自己的针对子应用的逻辑，那么最简单的方法就是实现自己的WebxController或者扩展AbstractWebxController。

<webx-configuration xmlns="http://www.alibaba.com/schema/services">
    <components defaultControllerClass="com.myframework.MyController"> ①
        <component name="app1">
            <controller class="com.myframework.MyController" /> ②
        </component>
    </components>
</webx-configuration>