Configuring Reverse Ajax

Reverse Ajax works in two basic modes, Active and Passive. Active Reverse Ajax can be broken down into three modes:

This page describes these modes, when they make sense, and how to configure them. However, first you need to enable Reverse Ajax which is described in the next section - General Configuration.

General Configuration

To use Reverse Ajax in any of the modes listed below the following general configuration is necessary:

  1. Set the activeReverseAjaxEnabled init-param on the DWRServlet to true:
    <servlet>
      <servlet-name>dwr-invoker</servlet-name>
      <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
      <init-param>
        <param-name>activeReverseAjaxEnabled</param-name>
        <param-value>true</param-value>
      </init-param>
    </servlet>
    
  2. Request Active Reverse Ajax from a web page:
    dwr.engine.setActiveReverseAjax(true);
    

Early Closing Mode

In Early Closing Mode, DWR holds connection open as in Full Streaming Mode, however it only holds the connection open for 60 seconds if there is no output to the browser. Once output occurs, DWR pauses for some configurable time (maxWaitAfterWrite) before closing the connection, forcing proxies to pass any messages on. To use Early Closing Mode in DWR 2.0.4 and onwards, no configuration is needed - this is the default. The maxWaitAfterWrite parameter defaults to 500 (ms) and can be configured through an init-param on the DWRServlet:

<init-param>
  <param-name>maxWaitAfterWrite</param-name>
  <param-value>1000</param-value>
</init-param>

In this case DWR will keep the connection open for an additional 1000 milliseconds after the first output in case there is additional output, before forcing a flush by closing the connection and requesting it to be re-opened.

The downside of Early Closing Mode is that for applications with a high rate of output, it can cause a large hit count. This can be countered by increasing the pause by setting maxWaitAfterWrite=1000 or similar.

In applications with a large number of connected browsers that are simultaneously sent a message they are likely to all try to reconnect at the same time. If you are affected by this type of problem, then you should consider investigating Full Streaming Mode.

A future version of DWR might attempt to automatically detect buggy proxies.

Full Streaming Mode (not available in IE)

Full Streaming mode has the fastest response characteristics because it closes connections only once every 60 seconds or so to check that the browser is still active. Due to limitations Internet Explorer users are unable to use Full Streaming mode. All Internet Explorer users will be automatically pushed to Early Closing mode.

The problem with full streaming is that it requires HTTP chunked mode which sometimes fails with network proxies, mod_jk, and other network scanners. If you try full streaming and find that messages are only getting through every 60 seconds, this could be why.

To enable Full Streaming Mode in DWR, use the maxWaitAfterWrite init-param with a -1 value:

<init-param>
  <param-name>maxWaitAfterWrite</param-name>
  <param-value>-1</param-value>
</init-param>

With a large number of connections held open, it is possible to thread starve an application server. Several web servers have a special mode to allow users to drop threads. DWR users also have the ability to create and plug-in a ServerLoadMonitor implementation that can dynamically modify the disconnected time, etc. if the server load gets too high. These features are discussed below.

Jetty

DWR makes use of Jetty Continuations from version 2.0. The Jetty support is automatic, no special configuration is needed.

Tomcat

Note:This feature is not currently working. You can still use DWR's reverse AJAX features with Tomcat but DWR will not take advantage of Tomcat's Asynchronous APIs (server will block). Please see/watch DWR-143 for updates.

For Tomcat you need to register a special version of the DwrServlet as follows:

<servlet>
  <servlet-name>dwr-invoker</servlet-name>
  <servlet-class>org.directwebremoting.server.tomcat.DwrCometProcessor</servlet-class>
  ...
</servlet>

You also need to use Tomcat's nio connector:

<Connector connectionTimeout="20000" port="8181"
   protocol="org.apache.coyote.http11.Http11NioProtocol" redirectPort="8443"/>

ServerLoadMonitor

DWR also provides a mechanism for you to create and plug-in your own implementation of ServerLoadMonitor which can adjust disconnected time, etc. based on server load. Plugging in a custom ServerLoadMonitor requires a web.xml init-param:

<servlet>
  <servlet-name>dwr-invoker</servlet-name>
  <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
  <init-param>
    <param-name>org.directwebremoting.extend.ServerLoadMonitor</param-name>
    <param-value>com.example.MyCustomServerLoadMonitor,com.example.MyCustomServerLoadMonitor</param-value>
  </init-param>
</servlet>

Polling Mode

If it is deemed unwise to hold connections open at all then DWR can use polling mode. In addition to the activeReverseAjaxEnabled=true init-param you should specify the PollingServerLoadMonitor as follows:

<init-param>
  <param-name>org.directwebremoting.extend.ServerLoadMonitor</param-name>
  <param-value>org.directwebremoting.impl.PollingServerLoadMonitor</param-value>
</init-param>

In polling mode the default poll rate is every 5 seconds. This can be customized using the following:

<init-param>
  <param-name>disconnectedTime</param-name>
  <param-value>60000</param-value>
</init-param>

The example above will poll only once every 60 seconds (60,000 milliseconds). For many applications a response time of 60 seconds will be enough, and will allow a web server to handle a very large number of clients.

There is a bug, fixed in DWR 2.0.2 where this parameter is badly mis-spelt. If you are using a version of DWR before 2.0.2 then you should use timeToNextPoll in place of disconnectedTime. The old spelling is deprecated rather than removed, however it will be removed in future releases.

Passive Mode

Passive Mode is the default if none of the options above are enabled. In passive mode, browsers do not make any extra connections to the web server. DWR queues data at the server in order to pass it on to clients. This transfer method is also known as the piggyback technique.

Passive Mode is the least responsive, however it does not place any extra load on the web-server.