第6章. engine.js 功能
engine.js对DWR非常重要，因为它是用来转换来至动态生成的接口的javascript函数调用的，所以只要用到DWR的地方就需要它。 每一个页面都需要下面这些语句来引入主DWR引擎。
<script type="text/javascript" src="/[YOUR-WEB-APP]/dwr/engine.js"> </script>
?6.1 使用选项
下面这些选项可以通过 DWREngine.setX() 函数来设置全局属性。例如：
DWREngine.setTimeout(1000);
?或者在单次调用级别上(假设Remote被DWR暴露出来了)：
Remote.singleMethod(params, {
callback:function(data) { ... },
timeout:2000
});
?远程调用可以批量执行来减少反应时间。endBatch 函数中可以设置选项。
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
? 一个例子:
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是个糟糕的做法。因为那样会使你的浏览器变慢。 要设置全局同步机制：
DWREngine.setAsync(true);
?
或者设置单次调用同步：
Remote.method(params, {
callback:function(data) { ... },
async:true
});
?或者在batch里面：
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就很有用了。 例如，要设置全局的远程调用方法：
DWREngine.setMethod(DWREngine.IFrame);
?
或者设置单次调用同步：
Remote.method(params, {
callback:function(data) { ... },
method:DWREngine.IFrame
});
?或者在batch里面：
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：
DWREngine.setVerb("GET");
?或者设置单次调用同步：
Remote.method(params, {
callback:function(data) { ... },
verb:"GET"
});
?或者在batch里面：
DWREngine.beginBatch();
Remote.method1(params, callback1);
Remote.method2(params, callback2);
DWREngine.endBatch({
verb:"GET"
});
?