【DWR系列04】- DWR配置详解

一、DWR配置简介

　　虽然使用DWR只需要简单的配置，但是DWR的功能还是很多的，如果要使用这些功能就要对DWR的配置进行了解。配置主要有web.xml，dwr.xml和注解配置。下面依次介绍。

二、DWR的web.xml配置

　　标准的DWR配置只需要配置一个servlet和servlet-mapping即可：

<servlet>
  <servlet-name>dwr-invoker</servlet-name>
  <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>dwr-invoker</servlet-name>
  <url-pattern>/dwr/*</url-pattern>
</servlet-mapping>

　　可选的参数有：

属性名称	默认值	简介	开始版本
jsonpEnabled	false	设置为true则支持JSONP	3.0RC2
allowGetForSafariButMakeForgeryEasier	false	设置为true可以让DWR工作在Safari 1.x（一个bug导致的问题）	2.0
crossDomainSessionSecurity	true	设置为false可以支持跨域	2.1
allowScriptTagRemoting	true	设置为true可以启用script标签的远程访问	2.0 rc4
debug	false	设置为true可以启用debug模式/测试页面	1.0
scriptSessionTimeout	1800000(30min)	设置scriptSessions的超时时间	2.0
maxCallCount	20	同一批最大调用数量	2.0rc2和1.1.4
activeReverseAjaxEnabled	false	设置为true启用轮询和长连接	2.0 RC3
pollAndCometEnabled	false	同activeReverseAjaxEnabled一样	2.0 RC1
maxWaitingThreads	100	等待线程的最大数量	2.0
maxHitsPerSecond	40	每秒最大的访问数量	2.0
[Interface	Name]	默认实现类，DWR允许你覆盖指定接口的实现	1.1
generateDtoClasses	interface	dwr服务端类的页面引用方式	2.0
ignoreLastModified	false	默认支持Last-Modified	2.0
normalizeIncludesQueryString	false	默认来说逆向Ajax对同一页面不同查询参数将会认为同一个页面	2.0 RC3
normalizeIncludesSessionID	false	默认来说逆向Ajax对同一页面不同session id将会认为同一个页面	3.0 RC2
overridePath	null	可以设置新的值覆盖路径到默认值	2.0
url:/about	dwr官方网站	可以设置为null不来显示它

2.1 配置dwr.xml路径

　　可以配置多个dwr.xml配置文件并指定路径：

<servlet>
  <servlet-name>dwr-user-invoker</servlet-name>
  <servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>
  <init-param>
    <param-name>config-user</param-name>
    <param-value>WEB-INF/dwr-user.xml</param-value>
  </init-param>
</servlet>
<servlet>
  <servlet-name>dwr-admin-invoker</servlet-name>
  <servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class>
  <init-param>
    <param-name>config-admin</param-name>
    <param-value>WEB-INF/dwr-admin.xml</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>dwr-admin-invoker</servlet-name>
  <url-pattern>/dwradmin/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
  <servlet-name>dwr-user-invoker</servlet-name>
  <url-pattern>/dwruser/*</url-pattern>
</servlet-mapping>

2.2 配置DWR插件

　　一般来说DWR允许你使用自己的实现，通过如下配置：

<servlet>
  <servlet-name>dwr-invoker</servlet-name>
  <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
  <init-param>
    <param-name>org.directwebremoting.extend.ServerLoadMonitor</param-name>
    <param-value>com.example.MyCustomServerLoadMonitor,com.example.MyCustomServerLoadMonitor</param-value>
  </init-param>
</servlet>

　　允许的插件有：

• org.directwebremoting.Container
• org.directwebremoting.HubFactory$HubBuilder
• org.directwebremoting.ServerContextFactory$ServerContextBuilder
• org.directwebremoting.WebContextFactory$WebContextBuilder
• org.directwebremoting.dwrp.FileUpload
• org.directwebremoting.extend.AccessControl
• org.directwebremoting.extend.AjaxFilterManager
• org.directwebremoting.extend.CallbackHelperFactory$CallbackHelperBuilder
• org.directwebremoting.extend.Compressor
• org.directwebremoting.extend.ContainerAbstraction
• org.directwebremoting.extend.ConverterManager
• org.directwebremoting.extend.CreatorManager
• org.directwebremoting.extend.DebugPageGenerator
• org.directwebremoting.extend.DownloadManager
• org.directwebremoting.extend.IdGenerator
• org.directwebremoting.extend.PageNormalizer
• org.directwebremoting.extend.Remoter
• org.directwebremoting.extend.ScriptSessionManager
• org.directwebremoting.extend.ServerLoadMonitor
• org.directwebremoting.extend.TaskDispatcherFactory$TaskDispatcherBuilder
• org.directwebremoting.json.parse.JsonParserFactory$JsonParserBuilder
• org.directwebremoting.json.serialize.JsonSerializerFactory$JsonSerializerBuilder
• org.directwebremoting.servlet.UrlProcessor
• org.directwebremoting.dwrp.HtmlPollHandler
• org.directwebremoting.dwrp.PlainCallHandler
• org.directwebremoting.dwrp.PlainPollHandler
• org.directwebremoting.dojo.DwrStoreHandler
• org.directwebremoting.servlet.DownloadHandler
• org.directwebremoting.servlet.EngineHandler
• org.directwebremoting.gi.GiHandler
• org.directwebremoting.servlet.IndexHandler
• org.directwebremoting.jsonp.JsonpCallHandler
• org.directwebremoting.jsonrpc.JsonRpcCallHandler
• org.directwebremoting.servlet.MonitorHandler
• org.directwebremoting.servlet.TestHandler
• org.directwebremoting.ui.servlet.UtilHandler
• org.directwebremoting.webwork.WebworkUtilHandler

2.3 测试模式

　　DWR有一个测试模式，通过配置来开启：

<init-param>
  <param-name>debug</param-name>
  <param-value>true</param-value>
</init-param>

　　开启后就可以通过访问主机名:端口/Web名/dwr/index.html：

　　可以看到系统中配置的可访问类被列出来了，点击进去：

　　可以看到一些帮助信息，也有对配置的类进行测试，重要的是开启debug模式后，日志信息会打印的更详细：

　　这在开发阶段非常有用，但是在部署环境上一定要将此属性注释掉，官方解释容易引起安全问题。

三、DWR的dwr.xml配置

3.1 dwr.xml文件简介

　　dwr.xml配置文件时DWR的标准配置文件，默认情况下你需要将其放到WEB-INF根目录下。一个dwr.xml的配置文件结构如下：

<!DOCTYPE dwr PUBLIC
    "-//GetAhead Limited//DTD Direct Web Remoting 3.0//EN"
    "http://directwebremoting.org/schema/dwr30.dtd">
<dwr>
    <!-- init只有在你扩展DWR的情况下才使用 -->
    <init>
        <creator id="..." class="..." />
        <converter id="..." class="..." />
    </init>
    <!-- 没有许可，DWR不能做任何事 -->
    <allow>
        <filter class="..." />
        <create creator="..." javascript="..." />
        <convert converter="..." match="..." />
    </allow>
    <!-- 你应该告诉DWR方法的参数泛型 -->
    <signatures>
        ...
    </signatures>
</dwr>

3.2 基本术语简介

　　首先了解dwr.xml配置文件的基本术语：

• <allow>：allow部分定义了哪些class能被DWR创建和转换以供全局过滤器使用。没有它DWR不能做任何工作。
• create：任何我们想要被js执行的Java类都需要在此标签创建，有几种创建模式，最常用的是new方式。
• convert：将类转换成js对象。这样js可以以对象的方式处理参数。
• filter：过滤器是用来在某些操作的时候进行相应处理。
• <init>：可选的配置部分，声明可以被创建并远程访问的类和可以被转换的类。
• <signatures>：DWR通过反射来找出哪种类型需要被创建。

　　dwr.xml配置文件可以有多个，多个配置文件需要在web.xml文件中声明。

3.3 Converters

　　转化器是DWR的重要组成部分，肩负着客户端和服务器数据转化责任。需要转化的有方法的参数对象和返回值对象。

+提示以下类型不需要转换

• 所有基本类型及其包装类，double、int、Integer等
• java.lang.String，java.util.Date和其3个SQL的派生类
• 以上所有类型的数组和集合
• 来自DOM，XOM，JDOM和DOM4J的DOM对象，如Element，Document
• 像byte[], java.io.InputStream, java.awt.image.BufferedImage或org.directwebremoting.io.FileTransfer的可以被浏览器下载的BOLB对象
• org.directwebremoting.io.JavascriptFunction的实例和org.directwebremoting.io.DwrConvertedException实例
• 服务端TIBCO GI CDF版本的文档，如jsx3.xml.CdfDocument.

3.3.1 基本转换示例

　　转换指定的一个类：

<convert converter="bean" match="com.example.Person"/>

　　转换指定包下的所有类：

<convert converter="bean" match="com.example.*"/>

　　转换指定包及其子包的所有类：

<convert converter="bean" match="com.example.**"/>

　　转换时排除指定类的指定属性：

<convert converter="bean" match="com.example.Person">
  <param name="exclude" value="property1, property2"/>
</convert>

　　转化时，只转化指定的属性：

<convert converter="bean" match="com.example.Person">
  <param name="include" value="property1, property2"/>
</convert>

　　对具有私有变量的Object对象进行反射转化：

<convert converter="object" match="com.example.Person">
  <param name="force" value="true"/>
</convert>

3.3.2 转换后调用

　　假如有以下代码，Person被转换，并可以被Remoted调用。

public class Remoted {
  public void addToFriends(Person p) {
    // ...
  }
}
public class Person {
  public void setName(String name) { ... }
  public void setAge(int age) { ... }
  // ...
}

　　那么js调用代码如下，将自动根据类型进行转换：

var p = { name:"Fred", age:21 };
Remoted.addToFriends(p);

3.3.3 集合转换支持

　　集合默认支持基本类型的转换，但是Map不支持null键，但是可以设置当出现null键的时候用什么来替代：

<convert converter="map" match="java.util.Map">
  <param name="nullKey" value="null"/>
</convert>

3.4 Creators

　　构造器的基本结构如下：

<allow>
  <create creator="..." javascript="..." scope="...">
    <param name="..." value="..."/>
    <auth method="..." role="..."/>
    <exclude method="..."/>
    <include method="..."/>
  </create>
  ...
</allow>

　　create具有以下属性（如果你想编写自己的构造器，那么你需要在<inti>部分进行声明。）：

• new：通过java的空的构造方法获得对象
• static：默认通过getInstance()获得对象
• none：不创建对象
• scripted：使用脚本语言创建对象
• spring：通过Spring容器获取对象
• jsf：通过JSF获取对象
• struts：使用Struts的formbeans对象
• pageflow：通过Beehive或Weblogic获得PageFlow
• ejb3：通过ejb获得对象

　　javascript属性：是必须的，是对象的js名称，避免使用js禁止的名称。

　　scope属性：有"application", "session", "request", "page" 和额外的"script"，默认为page，前四个属性和Web相似，script允许你有和HTTP session相似的功能但是不是用cookie而是绑定ID来实现。

　　param属性：用来对不同构造器进行配置的。

　　auth属性：允许你指定J2EE的角色属性。

　　include和exclude属性：用来指定需要包含或排除的方法。

3.5 Filters

　　过滤器用在响应前、响应后或者阻止响应。可以使用@Filter注解或者dwr:filter进行配置。格式如下：

<filter class="...">
  <param name="..." value="..."/>
</filter>

　　自定义过滤器必须实现org.directwebremoting.AjaxFilter接口，过滤器可以用作全局过滤：

<allow>
  <filter class="com.example.NoopFilter"/>
  ...
</allow>

　　或者局部过滤：

<allow>
  <create creator="...">
    <filter class="com.example.NoopFilter"/>
  </create>
  ...
</allow>

　　dwr 3.x提供一个用于模仿网络延时的过滤器：

<filter class="org.directwebremoting.filter.ExtraLatencyAjaxFilter">
  <param name="delay" value="200"/>
</filter>

　　配置为延时200ms，代表着调用前后各延时100ms，默认延时时间为100ms，代表前后各延时50ms。

3.6 Signatures

　　Signatures部分用来解决集合泛型问题，例如如下代码：

public class Check
{
  public List<?> setLotteryResults(List<?> whatDoIContain)
  {
      ...
  }
}

　　DWR不能知道集合中到底存了什么对象，但是当方法如下时就不需要了：

public class Check
{
  public List<Integer> setLotteryResults(List<Integer> whatDoIContain)
  {
      ...
  }
}

　　如果你坚持使用原始类型，那么就需要进行如下配置：

<signatures>
  <![CDATA[
  import java.util.List;
  import com.example.Check;
  Check.setLotteryResults(List<Integer> nos);
  ]]>
</signatures>

　　注意，signatures 元素不支持嵌套，以下配置将不起作用：

<signatures>
  <![CDATA[
  import java.util.List;
  import java.util.Map ;
  Check.setConditions(Map<String, Map<String, String>>);
  ]]>
</signatures>

四、DWR的注解配置

　　若要使用DWR的注解配置需要在web.xml中指定配置注解的类：

<servlet>
  <description>DWR controller servlet</description>
  <servlet-name>DWR controller servlet</servlet-name>
  <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
  <init-param>
    <param-name>classes</param-name>
    <param-value>
      com.example.RemoteFunctions,
      com.example.RemoteBean
    </param-value>
  </init-param>
</servlet>

　　如果配置的是内部类则使用$格式，例如使用java.util.Map$Entry而不是java.util.Map.Entry。

4.1 远程访问对象及方法

　　通过使用@RemoteProxy和@RemoteMethod注解来进行配置：

@RemoteProxy
public class RemoteFunctions {
    @RemoteMethod
    public int calculateFoo() {
       return 42;
    }
}

　　任何没有被@RemoteMethod声明的将不能被访问，也可以为远程对象重新定义名称：

@RemoteProxy(name="Functions")
    public class RemoteFunctions {
}

4.2 对象转换

　　通过使用@DataTransferObject和@RemoteProperty注解来进行配置：

@DataTransferObject
public class Foo {
    @RemoteProperty
    private int foo;
    public int getFoo() {
        return foo;
    }
    @RemoteProperty
    public int getBar() {
        return foo * 42;
    }
}

五、流式配置

　　这也是一种配置方式，如果想用流式配置代替dwr.xml配置方式，你需要这么做：

1. 创建org.directwebremoting.fluent.FluentConfigurator实现类，并重写configure()方法
2. 在web.xml的servlet新增参数customConfigurator，指向你的配置类

　　一个简单的流式配置如下：

public void configure() {
   withConverterType("dog", "com.yourcompany.beans.Dog");
   withCreatorType("ejb", "com.yourcompany.dwr.creator.EJBCreator");
   withCreator("new", "ApartmentDAO")
       .addParam("scope", session)
       .addParam("class", "com.yourcompany.dao.ApartmentDAO")
       .exclude("saveApartment")
       .withAuth("method", "role");
   withCreator("struts", "DogDAO")
       .addParam("clas", "com.yourcompany.dao.DogDAO")
       .include("getDog")
       .include("getColor");
   withConverter("dog", "*.Dog")
       .addParam("name", "value");
   withSignature()
       .addLine("import java.util.List;")
       .addLine("import com.example.Check;")
       .addLine("Check.setLotteryResults(List<Integer> nos);");
}

dwr.xml的配置方式选择

　　　　dwr.xml的配置方式简单、易修改、容易阅读，注解方式简单、流式配置方式复杂、不易修改，建议使用dwr.xml方式进行配置。