diff --git a/webx-guide/pom.xml b/webx-guide/pom.xml index 7bdf4dd..e0e30bf 100644 --- a/webx-guide/pom.xml +++ b/webx-guide/pom.xml @@ -72,6 +72,9 @@ + + + diff --git a/webx-guide/src/main/docbook/Webx3_Guide_Book.xml b/webx-guide/src/main/docbook/Webx3_Guide_Book.xml index fecc5f7..8f6e331 100644 --- a/webx-guide/src/main/docbook/Webx3_Guide_Book.xml +++ b/webx-guide/src/main/docbook/Webx3_Guide_Book.xml @@ -43,4 +43,10 @@ + + 简单使用 + + + + diff --git a/webx-guide/src/main/docbook/form/Webx3_Form.xml b/webx-guide/src/main/docbook/form/Webx3_Form.xml index f9e0c52..173fbd3 100644 --- a/webx-guide/src/main/docbook/form/Webx3_Form.xml +++ b/webx-guide/src/main/docbook/form/Webx3_Form.xml @@ -1213,7 +1213,7 @@ $group.mapTo($user) source内容，在中文环境中（locale=zh_CN），将显示错误信息“必须填写用户名”；而在英文环境中（locale=en_US），将显示默认的错误信息“User ID is required”。 系统的当前locale是由SetLocaleRequestContext来决定的。关于SetLocaleRequestContext的设定和使用，请参见。 + linkend="webx.requestcontexts"/> 此外，你还可以可以改变message source中key的前缀。 改变message source key的前缀 diff --git a/webx-guide/src/main/docbook/userguide/Webx3_pipeline.xml b/webx-guide/src/main/docbook/userguide/Webx3_pipeline.xml new file mode 100644 index 0000000..290aef3 --- /dev/null +++ b/webx-guide/src/main/docbook/userguide/Webx3_pipeline.xml @@ -0,0 +1,97 @@ + + + %placeholders; +]> + + + Pipeline 使用 +
+ 功能介绍 + pipeline是用来处理页面请求的。一个pipeline有多个valve组成，这些valve一般是按顺序执行，也就是一个请求进来，会经过一个个valve处理。 + 也有些valve有条件关系，如if/else，try,catch/finally类似有语义的valve组合，用于处理复杂的业务逻辑。 +
+
+ 概念解释 + valve：（阀门），页面请求的一个处理环节。如：analyzeURL，用来分析页面请求中所带参数，以方便业务代码中使用（target，action，actionEvent）。 +
+
+ 使用 + 常见pipelline的配置： <services:pipeline xmlns="http://www.alibaba.com/schema/services/pipeline/valves"> + + <!-- 初始化turbine rundata，并在pipelineContext中设置可能会用到的对象(如rundata、utils)，以便valve取得。 --> + <prepareForTurbine /> + + <!-- 设置日志系统的上下文，支持把当前请求的详情打印在日志中。 --> + <setLoggingContext /> + + <!-- 分析URL，取得target。 --> + <analyzeURL homepage="homepage" /> + + <!-- 检查csrf token，防止csrf攻击和重复提交。假如request和session中的token不匹配，则出错，或显示expired页面。 --> + <checkCsrfToken /> + + <loop> + <choose> + <when> + <!-- 执行带模板的screen，默认有layout。 --> + <pl-conditions:target-extension-condition extension="null, vm, jsp, jspx" /> + <performAction /> + <performTemplateScreen /> + <renderTemplate /> + </when> + <when> + <!-- 执行不带模板的screen，默认无layout。 --> + <pl-conditions:target-extension-condition extension="do" /> + <performAction /> + <performScreen /> + </when> + <otherwise> + <!-- 将控制交还给servlet engine。 --> + <exit /> + </otherwise> + </choose> + + <!-- 假如rundata.setRedirectTarget()被设置，则循环，否则退出循环。 --> + <breakUnlessTargetRedirected /> + </loop> + + </services:pipeline> + +
+
+ 原理 + pipeline的配置表明了页面处理顺序： + 如果是一个target后缀为null, vm, jsp, + jspx，则先执行action请求，再处理带模板的screen请求，最后才是渲染模板。所以不管是post表单提交也好，还是简单的页面请求也好，都是走这个顺序。 + 如果target后缀为do，则跟上面稍微有区别，不需要渲染模板，它在json请求等会有很大作用。 +
+
+ 扩展 + + + + 增加一个valve + 需要继承AbstractValve，并在配置文件配置,这样即可 + + <valve class="*.*" /> + + + + 增加一个后缀处理 + 如： + + <pl-conditions:target-extension-condition extension="json" /> + + 后面跟上要扩展的业务逻辑。 + + + 业务逻辑扩展 + 如csrftoken校验；页面权限校验。这些都可以通过pipeline来解决。 + 建议：增加的valve放到analyzeURL valve后面。前面几个valve涉及环境初始化工作。 + + + +
+ diff --git a/webx-guide/src/main/docbook/userguide/Webx3_pullservice.xml b/webx-guide/src/main/docbook/userguide/Webx3_pullservice.xml new file mode 100644 index 0000000..b523646 --- /dev/null +++ b/webx-guide/src/main/docbook/userguide/Webx3_pullservice.xml @@ -0,0 +1,113 @@ + + + %placeholders; +]> + + + Pipeline使用 +
+ 介绍 + pullService提供了一个自动组装template context的机制。除了框架提供的工具类之外，也可以自己做扩展。 +
+
+ 使用 +
+ 框架自带的tool +
+ <utils /> + + 注入了arrayUtil,classLoaderUtil,classUtil,exceptionUtil,fileUtil,localeUtil,messageUtil,objectUtil,streamUtil,stringEscapeUtil,stringUtil,systemUtil,mathUtil,这些工具类。 +   + + StringUtil类webx2时候差别蛮大的，使用前最好先查下类 + +
+
+ <rundata-tool /> + 注入了rundata，rundata对应的实例是：TurbineRunData +
+
+ <csrfToken /> + 注入了csrfToken，csrfToken对应的实例是：CsrfToken +
+
+ <form-tool /> + 注入了form +
+
+ <control-tool /> + 注入了ControlTool +
+
+ <uris-tool /> + 注入了所有uriBrokerService里面配的uriBroker。 +
+
+
+ toolName的生成规则顺序 + + + + refName + + + 根据class名字生成，如果类带后缀（Tool, ToolFactory, ToolSet, + ToolSetFactory），先去掉后缀，再变成camel case。如注入AbcTooFactory类，则页面可以引用abc。 + + + + 根据配置文件名称生成：如果配置带后缀（-tool, -tool-factory, -tool-set, + -tool-set-factory）,先去掉后缀，再变成camel case。如rundata-tool，页面引入的是rundata。 + + + + +
+
+
+ 扩展 +
+ 引入多个bean + <context-exposer> +     <tool id="bean1" /> +     <tool id="bean2" /> +     <tool id="bean3" /> +     <tool id="bean4" /> +</context-exposer> +
+
+ 注入类的常量（指的是public，static，finally的那些field），配置举例： + <constants id="myconst" constantClass="javax.servlet.http.HttpServletResponse" exposed="true/false"/> + 这样页面上就可以这么用常量，$myconst.SC_OK，$myconst.SC_FOUND  + + 默认exposed=true，这样模板上甚至可以这么用：$SC_OK，当然也可以这么$myconst.SC_OK，建议用后者。如果exposed=false，那模板上只能这么用：$myconst.SC_FOUND +
+
+ 注入一个类，举例： + <bean-tool id="beanName" class="com.alibaba...XXX" scope="global/request" autowire="true" /> +
+
+ 将静态util类的方法组合在一起，举例 + + <mixin id="myUtils"> + <!-- 引进class中所有public static方法 --> + <class name="com.alibaba.citrus.util.StringUtil" /> + + <!-- 引进class中部分public static方法 --> + <class name="com.alibaba.citrus.util.StringEscapeUtil"> + + <!-- 引进指定的public static方法 --> + <method name="escapeHtml" /> + + <!-- 引进指定的public static方法，并改名 --> + <method name="escapeURL" renameTo="escapeUrl" /> + + </class> +</mixin> + 这样在页面上可以这样使用：$myUtils.isEmpty("$ddd"),$myUtils.escapeHtml("$avar") + +
+
+ diff --git a/webx-guide/src/main/docbook/userguide/Webx3_uribrokerService.xml b/webx-guide/src/main/docbook/userguide/Webx3_uribrokerService.xml new file mode 100644 index 0000000..d4d3c72 --- /dev/null +++ b/webx-guide/src/main/docbook/userguide/Webx3_uribrokerService.xml @@ -0,0 +1,237 @@ + + + %placeholders; +]> + + + uriBrokerService 使用 +
+ 功能介绍 + uriBrokerService提供了uri的定制功能。以解决URI的拼接，转码，以及开发与正式环境切换的问题。 +
+
+ 使用 + + + + + + + + uri配置名称 + 含义 + 举例 + + + + + uri + 最通用的uri配置 + http://user:pass@myserver.com:8080/view?id=1#top + + + content-uri  + 通用的content URI，用于显示一般的WEB资源（如图片等） （静态资源一般用这种） + http://user:pass@myserver.com:8080/img/webx.jpg + + + servlet-uri  + Servlet风格的URI  + http://user:pass@myserver.com:8080/mycontext/myservlet/view?id=1#top + + + + servlet-content-uri  + 通用的servlet content URI，用于显示webapp context path下的资源（如图片等）  + http://user:pass@myserver.com:8080/mycontext/img/webx.jpg + + + turbine-classic-uri  + Turbine传统风格的URI（可以不考虑了）  + http://user:pass@myserver.com:8080/mycontext/turbine/template/product,ViewItem?id=1#top + + + + turbine-uri  + Turbine风格的URI (我们通常用这种) + + http://user:pass@myserver.com:8080/mycontext/myservlet/mycomponent/myTarget.jhtml + + + turbine-content-uri  + Turbine风格的content URI  + + http://user:pass@myserver.com:8080/mycontext/myservlet/mycomponent/myContent.jpg + + + uri-bean + 提供扩展机制 + + + + + +
+
+ uribroker配置介绍 +
+ uir配置介绍 + uri的配置由四部分组成：服务器信息，请求参数，属性，path。先举例： + + + + + + 1、请求参数；2、path；3、服务器信息；4、属性 + + 这个url生成后是：http://myuser2:mypass2@myservername2:1234/aaa/a1/bbb/ccc/ddd?aaa=1111&bbb=2222&ccc=3333#myreference2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
服务器参数配置说明
参数含义举例
serverURI 服务器URI http://www.alibaba.com
serverScheme 协议http 或者 https
loginUser 登录用户名 +
loginPassword 登录密码 +
serverName URL的服务器名称www.taobao.com
serverPort URL的服务器端口号 80
reference URL的参数参考说明 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
url配置属性说明
参数默认值含义
requestAware false 是否自动从request中填充值，默认不填充 
charset + 取得URL encoding的编码字符集。假如值为null，将从LocaleUtil中取得 
exposed false页面是否可引用，默认不可以
extends + 继承前一个uribroker
type null有四种：auto/full/absolute/relative auto：自动选择URI的类型  + full：完整URI，包括serverInfo, path; + absolute：绝对URI，不包括serverInfo，但包括完整的path;  + relative：相对URI，不包括serverInfo，其path为相对于当前请求的URI的相对路径 
+ +
+
+ content-uri 配置介绍 + content-uri 配置跟 uri 类似，不一样的是比uri配置增加了两个配置 : + prefixPath：Content前缀路径 ; + contentPath: Content路径  +
+
+ servlet-uri 配置介绍 + serlvet-uri 配置跟 uri 类似，不一样的是比uri配置增加了三个配置  + contextPath：Web应用程序context路径  + servletPath：Servlet路径  + pathInfo： URL的pathInfo部分  +
+
+ servlet-content-uri 配置 + serlvet-uri 配置跟 uri 类似，不一样的是比uri配置增加了三个配置  + contextPath：Web应用程序context路径  + prefixPath：Content前缀路径  + contextPath：Content路径 +
+
+ turbine-uri 配置 + turbine-uri 配置比uri增加了不少配置和属性。 + 配置如下： + contextPath:Web应用程序context路径 + servletPath: Servlet路径 + componentPath: Component路径 + target: target路径 + action: action名称 + 属性配置增加如下： + mappingRuleServiceRef: 引用mappingRuleService + targetMappingRule：目标mappingRule + actionParam: action   参数 + convertTargetCase: 是非将将target转换成target_name形式 +
+
+ turbine-content-uri 配置 + 比serlvet-content-uri多了一个componentPath +
+
+ uri-bean 配置 + 有两个属性：exposed和extend跟之前的使用一样。举例如下： + <uris:uri id="mybeanBase"> + <uris:serverURI>http://myserver/aa/bb/cc</uris:serverURI> +</uris:uri> + +<!-- 任意bean --> +<uris:uri-bean id="mybean" class="com.alibaba.citrus.service.uribroker.uri.GenericURIBroker" exposed="true" extends="mybeanBase" p:serverScheme="https" /> + myBean生成的url是：https://myserver/aa/bb/cc。如果有特殊的需求，可以在GenericURIBroker类或者直接在URIBroker上做扩展。 +
+
+ diff --git a/webx-guide/src/main/docbook/userguide/images/uribroker/1.png b/webx-guide/src/main/docbook/userguide/images/uribroker/1.png new file mode 100644 index 0000000..4ddeafa Binary files /dev/null and b/webx-guide/src/main/docbook/userguide/images/uribroker/1.png differ