dwr(2) 配置文件

dwr.xml文件的结构如下:

<!DOCTYPE dwr PUBLIC
    "-//GetAhead Limited//DTD Direct Web Remoting 1.0//EN"
    "http://www.getahead.ltd.uk/dwr/dwr10.dtd">

<dwr>

  <!-- init is only needed if you are extending DWR -->
  <init>
    <creator id="..." class="..."/>
    <converter id="..." class="..."/>
  </init>

  <!-- without allow, DWR isn't allowed to do anything -->
  <allow>
    <create creator="..." javascript="..."/>
    <convert converter="..." match="..."/>
  </allow>

  <!-- you may need to tell DWR about method signatures -->
  <signatures>
    ...
  </signatures>

</dwr>

<allow>

在它里面内容都是dwr可以转换或创建的。

<create>

每个类都需要一个<create ...>定义。creator有几种，比较通用的是new关键字和Spring。creator属性 是必须的， 它用来指定使用那种创造器。

默认情况下DWR有8种创造器。它们是：

• new: 用Java的new关键字创造对象。
• none: 它不创建对象，看下面的原因。 (v1.1+)
• scripted: 通过BSF使用脚本语言创建对象，例如BeanShell或Groovy。
• spring: 通过Spring框架访问Bean。
• jsf: 使用JSF的Bean。 (v1.1+)
• struts: 使用Struts的FormBean。 (v1.1+)
• pageflow: 访问Beehive或Weblogic的PageFlow。 (v1.1+)
• ejb3: An experimental Creator to give access to EJB3 session beans. This code should not be seen as production quality until it has undergone more testing, and has an official maintainer. (v2.0+)

如果你需要写自己的创造器，你必须在init部分注册它。

javascript属性： 用于指定浏览器中这个被创造出来的对象的名字。不能使用Javascript的关键字。

scope属性： 非常类似servlet规范中的scope。 它允许你指定这个bean在什么生命范围。选项有"application", "session", "request" 和"page"。这些值对于Servlet和JSP开发者来说应该相当熟悉了。

scope属性是可选的。默认是"page"。如果要使用"session"需要cookies。

（

The scope attribute is largely the same as the scope attribute as defined by the servlet spec. It allows you to specify what a bean is available to. The options are "application", session, "request", "page" and an additional scope "script". These first 4 of these values should be familiar to Servlet and JSP developers. "script" scope allows you to have something similar to an HTTP session that is tied to an ID in a page rather than in a cookie.

The scope attribute is optional. It defaults to "page".

）

param元素： 被用来指定创造器的其他参数，每种构造器各有不同。例如，"new"创造器需要知道要创建的对象类型是什么。每一个创造器的参数在各自的文档中能找到。

include和exclude元素： 允许创造器来限制类中方法的访问。一个创造器必须指定include列表或exclude列表之一（官方文档说必须指定一个include列表或exclude列表，但是如果都不指定的话类中的方法都可以访问。include列表或exclude列表只能有一个，不能同时存在）。如果是include列表则暗示默认的访问策略是"允许"；如果是exclude列表则暗示默认的访问策略是"拒绝"。

（The include and exclude elements allow a creator to restrict access to class methods. A Creator should specify EITHER a list of include elements (which implies that the default policy is denial) OR a list of exclude elements (which implies that the default policy is to allow access)）

For example to deny access to all methods in some class except for the setWibble() method you should put the following into your dwr.xml。如果类中除了setWibble() 其他的方法都不能使用，配置如下

<create creator="new" javascript="Fred">
  <param name="class" value="com.example.Fred"/>
  <include method="setWibble"/>
</create>

auth元素 允许你指定一个J2EE的角色作为将来的访问控制检查:

<create creator="new" javascript="Fred">
  <param name="class" value="com.example.Fred"/>
  <auth method="setWibble" role="admin"/>
</create>

<converter>

转换器

转换器在客户端和服务器之间转换数据.

下面这些转换器有单独章节介绍

• Array Converter
• Bean and Object Converters
• Collection Converter
• Enum Converter
• DOM Objects
• Hibernate整合
• Servlet Objects (HttpServletRequest, HttpSession, etc)

http://wiki.javascud.org/display/dwrcn/Converters

基础的转换器

原生类型，String，像BigDecimal这样的简单对象的转换器已经有了。你不需要在dwr.xml中<allow>部分的<convert>中定义。它们默认支持。

默认支持的类型包括： boolean, byte, short, int, long, float, double, char, java.lang.Boolean, java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float, java.lang.Double, java.lang.Character, java.math.BigInteger, java.math.BigDecimal 和 java.lang.String

签名(Signatures)

signatures段使DWR能确定集合中存放的数据类型。例如下面的定义中我们无法知道list中存放的是什么类型。

public class Check
{
  public void setLotteryResults(List nos)
  {
      ...
  }
}

signatures段允许我们暗示DWR应该用什么类型去处理。格式对以了解JDK5的泛型的人来说很容易理解。

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

DWR中又一个解析器专门来做这件事，所以即便你的环境时JDK1.3 DWR也能正常工作。

解析规则基本上会和你预想规则的一样(有两个例外)，所以java.lang下面的类型会被默认import。

第一个是DWR1.0中解析器的bug，某些环境下不能返回正确类型。所以你也不用管它了。

第二个是这个解析器时"阳光(sunny day)"解析器。就是说它非常宽松，不像编译器那样严格的保证你一定正确。所以有时它也会允许你丢失import。

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

嵌套定义泛型

dwr目前不支持嵌套泛型定义。所以下面的例子不能正常工作：

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

在dwr支持嵌套泛型定义之前，可以有下面的方式：

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

signatures段只是用来确定泛型参数中的类型参数。DWR会自己使用反射机制或者运行时类型确定类型，或者假设它是一个String类型。所以：

不需要signatures - 没有泛型参数：

public void method(String p);
public void method(String[] p);

需要signatures - DWR不能通过反射确定：

public void method(List<Date> p);
public void method(Map<String, WibbleBean> p);

不需要signatures - DWR能正确的猜出:

public void method(List<String> p);
public void method(Map<String, String> p);

不需要signatures - DWR可以通过运行时类型确定：

public List<Date> method(String p);

没有必要让Javascript中的所有对象的key都是String类型 - 你可以使用其他类型作为key。但是他们在使用之前会被转换成String类型。DWR1.x用Javascript的特性把key转换成String。DWR2.0可能会用toString()方法，在服务段进行这一转换。

<filter>过滤器

过滤器使用<filter>在dwr.xml中定义、@filter、<dwr:filter>元素在spring配置文件中定义。

<filter class="...">
  <param name="..." value="..."/>
</filter>
filter可以是allow的子元素，也可以是create子元素

class属性是必须的，它必须有完整的包名，并且实现org.directwebremoting.AjaxFilter 接口。这个接口只有一个方法doFilter。

在spring配置文件中这样写

bean id="..." class="...">
  <dwr:remote javascript="...">
    <dwr:filter class="..."/>
  </dwr:remote>
</bean>
下面例子中的过滤期什么也不做

package com.example;

public class NoopFilter {
  public Object doFilter(Object obj, Method method, Object[] params, AjaxFilterChain chain) throws Exception {
    return chain.doFilter(obj, method, params);
  }
}
在dwr.xml中全局过滤器这样配置

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

为一个class配置过滤器

<allow>
  <create creator="...">
    <filter class="com.example.NoopFilter"/>
  </create>
  ...
</allow>
过滤器中可以使用param元素，例如<param name="foo" value="bar"/> dwr会调用filter.setFoo("bar") 在构造之后使用之前。

使用过滤期可以实现一下功能

1.记录函数调用日志

2.执行前进行安全检查，如果不满足条件就抛异常

3.检查方法参数的正确性

4.测试中故障模拟

DWR 2.0包含一个内置的过滤器用于模拟网络的延迟，配置如下：

<filter class="org.directwebremoting.filter.ExtraLatencyAjaxFilter">
  <param name="delay" value="200"/>
</filter>
这个配置模拟在dwr执行前后有200毫秒的延迟。也就是在每个调用的前后分别有100毫秒。默认值100毫秒（每个调用前后各50毫秒）