Retry Logic

DWR has built-in automatic retry logic for reverse AJAX/polling calls. Our default retry configuration will work well for the great majority of our users provided that a custom pollStatusHandler has been set. If you would like to learn more about how our default retry policy works or would like to customize it please continue reading.

How are default retry policy works

When a problem occurs on a polling request any registered errorHandlers will be ignored. DWR's retry policy will be initiated and in 1 second DWR will try another poll request. If this poll request fails DWR will try another poll request in 3 seconds. If this poll request fails DWR will go offline. At this point DWR will call the pollStatusHandler with a flag indicating that DWR is offline and continue to check for a heartbeat indefinitely at 3 second intervals. If a connection is re-established while DWR is offline the pollStatusHandler will be called with a flag indicating that DWR is back online.

Please note that a custom pollStatusHandler should be set (dwr.engine.setPollStatusHandler) otherwise the errorHandler will be used. If the errorHandler is used it will only be called when DWR goes offline, it will NOT be called when a connection is re-established.

Custom Retry Policy

If our default retry policy doesn't fit your needs the policy is highly configurable - please read the sections below to learn more.

Retry Intervals

At the heart of the DWR retry policy is the retryIntervals array. The default array [ 1, 3, 3 ] may be overridden by calling dwr.engine.setRetryIntervals. An explanation of the retryIntervals array:
  1. retryIntervals[0 through retryIntervals.length - 1] - Each value in this range indicates a retry interval - DWR is still online!
  2. retryIntervals.length - 1 = The number of retry attempts until DWR is offline.
  3. retryIntervals[retryIntervals.length - 1] = The heartbeat interval - how often we check for a re-established connection when DWR is offline.

Poll Status handler

The pollStatusHandler is a function DWR calls when:
  1. DWR goes offline
  2. DWR comes back online
  3. maxRetries has been reached
In all cases flags will be passed to the handler specifying DWR's status: 
dwr.engine._pollStatusHandler(newStatus, ex, maxRetriesReached)
Please note: a custom pollStatusHandler should be set (dwr.engine.setPollStatusHandler) otherwise the errorHandler will be used. If the errorHandler is used it will only be called when DWR goes offline, it will NOT be called when a connection is re-established.

Max Retries

Once DWR is offline, the default behavior is to check for a re-established connection indefinitely. If this is not the desired behavior the maxRetries property may be set (dwr.engine.setMaxRetries). If this property is set, once it has been reached the pollStatusHandler will be called with a flag indicating that the maximum number of retries has been reached. Please note that the maxRetries flag includes the retries attempted while DWR was online.

Examples

A working example of the retry logic can be seen in the dwr.war - clock example.