engine.js Functions

engine.js is vital to DWR since it is used to marshal calls from the dynamically generated JavaScript interfaces to the server. All pages where DWR will be used require the inclusion of engine.js:

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

All engine.js functions have the dwr.engine prefix.

Using the options

These options may be set globally using a dwr.engine.setX() function. For example:

dwr.engine.setTimeout(1000);

Or on a per call basis:

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). If you set an option several times in a batch, the last setting will be used. So if the Remote.singleMethod() example discussed previously was included in the batch example above, a timeout of 3000ms would be used for the batch.

Two of the options, callback and exceptionHandler, are always specific to a call and not to a batch.

Two 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.

Option index

The following options are available.

Option Global Batch Call Summary
async 1.1 1.1 1.1 Set to false for asynchronous behaviour (highly discouraged).
headers 2.0 2.0 2.0 Extra headers to add to XHR calls.
attributes 3.0 - - Meta-data that is made available through request.getAttribute(attrName).
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.
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 - - true if DWR should provide ordering guarantees.
activeReverseAjax 2.0 - - Should we be looking for inbound calls?
notifyServerOnPageUnload 3.0 - - Should we notify the server that the page has been unloaded? Please see our reverse AJAX hints and tips for more information.
maxRetries 3.0 RC2 - - Defaults to -1, unlimited.

Please see our Retry handling documentation.
retryIntervals[] 3.0 RC2 - - Defaults to [1, 1, 3].

Please see our Retry handling documentation.
pollStatusHandler 3.0 RC2 - - Defaults to the errorHandler. This default should generally be overridden for active Reverse Ajax users.

Please see our Retry handling documentation.

Guaranteed Responses

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.