engine.js Functions
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>
Using the options
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.
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 (not
recommended). |
| 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 | - | - | For reverse AJAX calls. The number of times we should re-attempt failed calls after DWR has went offline. Defaults to -1, unlimited. |
| retryIntervals[] | 3.0 RC2 | - | - | For reverse AJAX calls. An array specifying the default time
between retries (in seconds). Defaults to: [ 1, 1, 10 ] retryIntervals.length - 1 = The number of retry attempts until DWR is offline. retryIntervals[retryIntervals.length - 1] = The interval used to poll the server while DWR is offline. In this case the first retry will occur in 1 second and the second retry will occur in 1 second - DWR will be offline if both of these retries are unsuccessful. While DWR is offline we will continue to poll for server status every 10 seconds until maxRetries is reached. When DWR goes offline or online pollStatusHandler will be called. |
| pollStatusHandler | 3.0 RC2 | - | - | Function to call when the server comes online or offline. For reverse Ajax polling. |
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.