DWR中文文档v0.9 07

第6章. engine.js 功能
engine.js对DWR非常重要，因为它是用来转换来至动态生成的接口的javascript函数调用的，所以只要用到DWR的地方就需要它。 每一个页面都需要下面这些语句来引入主DWR引擎。

Java代码

1. <script type="text/javascript" src="/[YOUR-WEB-APP]/dwr/engine.js">   
2.  </script>  

<script type="text/javascript" src="/[YOUR-WEB-APP]/dwr/engine.js">
 </script>

 6.1 使用选项
下面这些选项可以通过 DWREngine.setX() 函数来设置全局属性。例如：

Java代码

1. DWREngine.setTimeout(1000);  

DWREngine.setTimeout(1000);

 或者在单次调用级别上(假设Remote被DWR暴露出来了)：

Java代码

1. Remote.singleMethod(params, {    
2.    callback:function(data) { ... },    
3.    timeout:2000    
4. });  

Remote.singleMethod(params, { 
   callback:function(data) { ... }, 
   timeout:2000 
});

 远程调用可以批量执行来减少反应时间。endBatch 函数中可以设置选项。

Java代码

1. DWREngine.beginBatch();   
2.  Remote.methodInBatch1(params, callback1);    
3. Remote.methodInBatch2(params, callback2);    
4. DWREngine.endBatch({   
5.  timeout:3000    
6. });  

DWREngine.beginBatch();
 Remote.methodInBatch1(params, callback1); 
Remote.methodInBatch2(params, callback2); 
DWREngine.endBatch({
 timeout:3000 
});

 可以混合这几种方式，那样的话单次调用或者批量调用级别上的设置可以复写全局设置(就像你希望的那样)。当你在一个批量处理中多次设置了某个选项，DWR会保留最后一个。所以如果 Remote.singleMethod() 例子在batch里面，DWR会使用3000ms做为超时的时间。 callback和exceptionHandler两个选项只能在单次调用中使用，不能用于批量调用。 preHook和postHook选项两个选项是可添加的，就是说你可以为每一次调用添加多个hook。全局的preHook会在批量调用和单次调用之前被调用。同样全局的postHook会在单次调用和批量调用之后被调用。 如果以上叙述让你感到混乱，不用担心。DWR的的设计往往和你想象中的一样，所以其实这些并不复杂
 6.2 选项索引
下面是可用选项列表。

Option       Global     Batch     Call             Summary
async          1.1          1.1        1.1     设置是否为异步调用，不推荐同步调用
headers      2.0          2.0        2.0     在XHR调用中加入额外的头信息
parameters 2.0          2.0        2.0     可以通过Meta-datarequest.getParameter()取得的元数据
httpMethod 2.0          2.0        2.0     选择GET或者POST. 1.x中叫 “verb”
rpcType       2.0          2.0        2.0    选择是使用xhr, iframe或者script-tag来实现远程调用. 1.x中叫”method”
skipBatch    1.0*       2.1?        -       某个调用是否应该设置为batch中的一部分或者直接的。这个选项和上面都有些

                                                      不同。 *没有setSkipBatch()方法，批量调用是通过beginBatch()

                                                        和  endBatch()来控制的。

timeout       1.0         1.1          1.1      设定超时时长，单位ms
6.2.1 处理器(Handler)         

 Option               Global    Batch   Call         Summary
errorHandler        1.0        1.1      1.1          当出了什么问题时的动作。1.x中还包括服务端的异常。从2.0开始服务

                                                                  端异常通过”exceptionHandler”处理
warningHandler   1.0        2.0     2.0          当因为浏览器的bug引起问题时的动作，所以默认这个设置为null(关闭)
textHtmlHandler   2.0       2.0     2.0          当得到不正常的text/html页面时的动作(通常表示超时)
6.2.2 调用处理器(Call Handler)

 Option             Global      Batch   Call         Summary
callback            -                 -        1.0         调用成功以后的要执行的回调函数，应该只有一个参数：远程调用得到的

                                                                  数据
exceptionHandler   -        -           2.0         远程调用失败的动作，一般是服务端异常或者数据转换问题。
 
6.2.3 Hooks (一个batch中可以注册多个hook)

Option             Global    Batch    Call       Summary
preHook          1.0          1.1       1.1        远程调用前执行的函数
postHook        1.0          1.1       1.1        远程调用后执行的函数

6.2.4 全局选项(在单次调用或者批量调用中不可用)

 Option           Global      Batch      Call           Summary
ordered          1.0            -             -               DWR是否支持顺序调用
pollType          2.0           -             -                选择xhr或者iframe的反转Ajax
reverseAjax    2.0           -             -                是否查找inbound调用

6.2.5 废弃的选项

Option           Global      Batch      Call           Summary
verb              1.0           1.1          1.1            2.0废弃。使用 “httpMethod”代替
method         1.0           1.1          1.1            2.0废弃。使用 “rpcType”代替

6.2.6 未来版本的选项

Option                      Global      Batch      Call           Summary
onBackButton             2.1?         2.1?         -              用户按了back按钮后的动作
onForwardButton       2.1?         2.1?         -            用户按了forward按钮的动作

 6.3 选项说明

 

6.3.1 批量调用
你可以使用batch来批量的执行远程调用。这样可以减少与服务器的交互次数，所以可以提交反应速度。

 一个batch以 DWREngine.beginBatch() 开始 ，并以 DWREngine.endBatch() 结束。当 DWREngine.endBatch() 被调用，我们就结束了远程调用的分组，这样DWR就在一次与服务器的交互中执行它们。

DWR会小心的处理保证所有的回调函数都会被调用，所以你可以明显的打开和关闭批处理。只要别忘了调用endBatch()，否则所有的远程调用永远的处于列队中。

 警告：很明显，把一些远程调用放在一起执行也会产生一些影响。例如不能在batch里面执行同步调用。 所有的元数据选项，例如hooks, timeouts和errorHandlers都在batch级别的，而不是单次调用级别上的。所以如果一个batch中有两个调用设置了不同的超时，除了最后一个其他的都被忽略。

6.3.2 顺序调用

 

因为Ajax一般是异步调用，所以远程调用不会按照发送的顺序返回。DWREngine.setOrdered(boolean) 允许结果严格按照发送的顺序返回。DWR在旧的请求安全返回以后才去发送新的请求。

 我们一定需要保证请求按照发送的顺序返回吗？（默认为false）

 警告 ： 把这个设置为true会减慢你的应用程序，如果一个消息丢失，浏览器就会没有响应。很多时候即使用异步调用也有更好的解决办法，所以在用这一功能之前先好好考虑一下。

6.3.3 错误警告和超时

 处理错误和警告
当因为一些原因调用失败，DWR就会调用错误和警告handler(根据错误的激烈程度)，并传递错误消息。 你可以用这种方法来在alert窗口或状态来中显示错误信息。 你可以使用DWREngine.setErrorHandler(function)来改变错误处理方式，同样通过DWREngine.setWarningHandler(function)来改变警告处理方式。
 设置超时
DWREngine.setTimeout()，单次调用和批量调用级别的元数据选项，允许你设置一个超时值。全局的DWREngine.setTimeout()函数设置全局超时。如果设置值为0(默认)可以将超时关掉。 setTimeout()的单位是毫秒。如果调用超时发生，错误处理器就会被调用。
51 / 92
 一个例子:

Java代码

1. Remote.method(params, {    
2.     callback:function(data) { alert("it worked"); },       
3.     errorHandler:function(message) { alert("it broke"); },    
4.     timeout:1000    
5. });  

Remote.method(params, { 
    callback:function(data) { alert("it worked"); },    
    errorHandler:function(message) { alert("it broke"); }, 
    timeout:1000 
});

 如果Remote.method()调用超过了1分钟还没有返回，"it broke"消息就会被显示。

6.3.4 远程调 Hooks

 

 

DWREngine.setPreHook(function) 和 DWREngine.setPostHook(function) 。

 如果你想在DWR调用之前出现一个提示，你可以设置pre-hook函数。它将会被调用，但是没有参数传递到这个函数。当你希望让一些按钮在调用期间变灰来防止被再次使用，这一功能将会很有用。

 post-hook用来和pre-hook一起使用来逆转pre-hook产生的做的一些改变。 一个使用pre和post hook的例子就是 DWRUtil.useLoadingMessage() 函数。

6.3.5 远程调用选项

DWR有一些选项用来控制远程调用的处理方式。method和verb对于用户应该时透明的，但是不同的浏览器效果的可能不一样。一般来说DWR会选择正确方法来处理，但是这些选项对于在不同效果的浏览器之间开发很有用。
 DWREngine.setAsync(flag)
DWR1.0不支持。 我们指定让XHR异步调用了吗？ 默认为true。警告如果你使用的时IFrame或者ScriptTag这一选项被忽略。一般来说把他变成false是个糟糕的做法。因为那样会使你的浏览器变慢。 要设置全局同步机制：

Java代码

1. DWREngine.setAsync(true);  

DWREngine.setAsync(true);

或者设置单次调用同步：

Java代码

1. Remote.method(params, {    
2.     callback:function(data) { ... },    
3.     async:true    
4. });  

Remote.method(params, { 
    callback:function(data) { ... }, 
    async:true 
});

 或者在batch里面：

Java代码

1. DWREngine.beginBatch();    
2. Remote.method1(params, callback1);    
3. Remote.method2(params, callback2);    
4. DWREngine.endBatch({    
5.      async:true    
6. });  

DWREngine.beginBatch(); 
Remote.method1(params, callback1); 
Remote.method2(params, callback2); 
DWREngine.endBatch({ 
     async:true 
});

 用来设置恰当的方法。setMethod()不能把正使用你选择的方法，它只是保证首先尝试使用那个方法。newmethod必须是DWREngine.XMLHttpRequest或者DWREngine.IFrame，或者2.0以后的DWREngine.ScriptTag。

XMLHttpRequest时默认的，并且大多情况下可用。当ActiveX禁用IFrame就有用了，尽管DWR能自动检测出这种情况并切换到IFrame。当你要突破跨域调用的限制，ScriptTag就很有用了。 例如，要设置全局的远程调用方法：

Java代码

1. DWREngine.setMethod(DWREngine.IFrame);  

DWREngine.setMethod(DWREngine.IFrame);

或者设置单次调用同步：

Java代码

1. Remote.method(params, {    
2.    callback:function(data) { ... },    
3.    method:DWREngine.IFrame    
4. });  

Remote.method(params, { 
   callback:function(data) { ... }, 
   method:DWREngine.IFrame 
});

 或者在batch里面：

Java代码

1. DWREngine.beginBatch();    
2. Remote.method1(params, callback1);    
3. Remote.method2(params, callback2);    
4. DWREngine.endBatch({   
5.      method:DWREngine.IFrame    
6. });  

DWREngine.beginBatch(); 
Remote.method1(params, callback1); 
Remote.method2(params, callback2); 
DWREngine.endBatch({
     method:DWREngine.IFrame 
});

  DWREngine.setVerb(verb)

这个选项允许你选择POST和GET，无论时用iframe还是XMLHttpRequest方法。一些浏览器(例如，旧版的Safari)不支持XHR-POST所以DWR就自动切换到GET，即使你设置POST为verb。所以setVerb()应当被仅仅做为一个堤示。 如果使用ScriptTag来远程调用，设置verb时没有的。
 
例如，设置全局远程调用的verb：

Java代码

1. DWREngine.setVerb("GET");  

DWREngine.setVerb("GET");

 或者设置单次调用同步：

Java代码

1. Remote.method(params, {   
2.     callback:function(data) { ... },    
3.      verb:"GET"  
4.  });  

Remote.method(params, {
    callback:function(data) { ... }, 
     verb:"GET"
 });

 或者在batch里面：

Java代码

1. DWREngine.beginBatch();   
2.  Remote.method1(params, callback1);   
3.  Remote.method2(params, callback2);    
4. DWREngine.endBatch({    
5.    verb:"GET"    
6. });  

DWREngine.beginBatch();
 Remote.method1(params, callback1);
 Remote.method2(params, callback2); 
DWREngine.endBatch({ 
   verb:"GET" 
});