engine.js is vital to DWR since it is used to marshal calls from the dynamically generated interface JavaScript function, so it is needed wherever DWR is used.
All engine.js functions have the dwr.engine prefix.
The engine.js file
All DWR pages need the following script element to import the main DWR engine.
<script type='text/javascript'
src='/[YOUR-WEB-APP]/dwr/engine.js'>
</script>
These options may be set globally using a dwr.engine.setX() function. For example:
dwr.engine.setTimeout(1000);
Or at a call level (Assume Remote is exported by DWR):
Remote.singleMethod(params, {
callback:function(data) { ... },
timeout:2000
});
Remote calls can be batched together to reduce latency. Options can also be set on the endBatch() method:
dwr.engine.beginBatch();
Remote.methodInBatch1(params, callback1);
Remote.methodInBatch2(params, callback2);
dwr.engine.endBatch({
timeout:3000
});
It is possible to mix these styles, in which case call or batch level settings override global settings (as you would expect). When if you set an option several times in a batch, the last setting is taken. So if the Remote.singleMethod() example above was included in the batch, a timeout of 3000ms would be used for the batch.
2 of the options, callback and exceptionHandler, are always specific to a call and not to a batch.
2 of the options, preHook and postHook, are additive, that is you can have multiple hooks per call. The global preHook is called before the batch and call preHooks. The global postHook is called after the call and batch postHooks.
If all of this sounds confusing then don't worry. DWR is designed to do what you expect, so it should not be complex.
The following options are available.
| Option | Global | Batch | Call | Summary |
|---|---|---|---|---|
| async | 1.1 | 1.1 | 1.1 | Set to false for asynchronous behaviour (not recommended) |
| headers | 2.0 | 2.0 | 2.0 | Extra headers to add to XHR calls. |
| parameters | 2.0 | 2.0 | 2.0 | Meta-data that is made available through request.getParameter() |
| timeout | 1.0 | 1.1 | 1.1 | Cancel request after X ms |
| Handlers | ||||
| errorHandler | 1.0 | 1.1 | 1.1 | Action when something is broken. In 1.x this included server-side exceptions. From 2.0, server side exceptions use 'exceptionHandler' |
| warningHandler | 1.0 | 2.0 | 2.0 | Action when something breaks which can be triggered by browser bugs, so by default this is set to null (turned off) |
| textHtmlHandler | 2.0 | 2.0 | 2.0 | Action when an unexpected text/html page is received (usually indicates session timeout) |
| Call Handlers (Registered for individual calls not all calls in a batch) | ||||
| callback | - | - | 1.0 | Executed on successful call completion with a single parameter; the returned data. |
| callbackHandler | - | - | 3.0 | Synonymous with callback to match exceptionHandler. |
| exceptionHandler | - | - | 2.0 | Executed when a remote call fails either due to a server exception or a data marshalling problem. |
| arg | - | - | 3.0 | A default argument to pass to the callbackHandler and exceptionHandler. |
| callbackArg | - | - | 3.0 | An argument to pass to the callbackHandler. If specified overrides arg. |
| exceptionArg | - | - | 3.0 | An argument to pass to the exceptionHandler. If specified overrides arg. |
| scope | - | - | 3.0 | The scope in which the callbackHandler and exceptionHandler will be executed. Default is window. |
| callbackScope | - | - | 3.0 | The scope in which the callbackHandler will be executed. If specified overrides scope. |
| exceptionScope | - | - | 3.0 | The scope in which the exceptionHandler will be executed. If specified overrides scope. |
| Hooks (Multiple hooks can be registered per batch) | ||||
| preHook | 1.0 | 1.1 | 1.1 | Function called just before the remote call |
| postHook | 1.0 | 1.1 | 1.1 | Function called just after the remote call |
| Global Options (Not available at a call or batch level) | ||||
| ordered | 1.0 | - | - | Should DWR provide ordering guarantees |
| activeReverseAjax | 2.0 | - | - | Should we be looking for inbound calls |
| Deprecated Options | ||||
| httpMethod | 2.0 | 2.0 | 2.0 | Selects use of GET or POST. Called 'verb' in 1.x, likely to be removed in version 3.0 |
| rpcType | 2.0 | 2.0 | 2.0 | Selects between xhr, iframe or script-tag remoting. Called 'method' in 1.x, likely to be removed in version 3.0 |
| pollType | 2.0 | - | - | Selects between xhr and iframe for Reverse Ajax |
| verb | 1.0 | 1.1 | 1.1 | Deprecated in 2.0. Use 'httpMethod' instead |
| method | 1.0 | 1.1 | 1.1 | Deprecated in 2.0. Use 'rpcType' instead |
DWR aims to be able to tell you exactly what happened to all calls. Given the existence of browser bugs this can be tricky in places.
If you set a callback, exceptionHandler, errorHandler, warningHandler and textHtmlHandler then DWR should always give you a response for each request.