A Field Guide to Java Direct Web Remoting (DWR)

In this article, I will discuss the Direct Web Remoting (DWR) technology developed by Joe Walker and maintained by the small IT consultancy Getahead in UK. This technology is a unique way of Ajax-enabling existing Java server-side code by exposing it in JavaScript. This sounds complicated but, in reality, the technology is relatively straightforward. It has some limitations, such as exposing overloaded Java methods or marshaling of very complex Java Objects to JavaScript and will work only in a web application server. But overall, DWR is a very powerful concept that works with any existing Java web application and makes the process of web remoting easier.

Introduction to DWR

If you are familiar with the Web Services specification, the DWR can appear to be conceptually very similar. In Web Services, Java code is “exposed” via a Web Services Definition Language (WSDL) XML file, and external clients connect via stub code by using a predefined protocol. The clients query the exposed methods, and objects travel from the server in a SOAP XML format. With the DWR, the Java code is also defined via a custom XML file and “exposed” via a special Servlet. DWR clients connect via AJAX/JavaScript stub code using a predefined custom protocol and query the exposed methods in JavaScript. DWR is a Java-only technology, whereas Web Services are standards based and are not language specific. However, because of its unique approach to using Ajax and ease of use, DWR technology quietly gained popularity among Java developers. DWR is a freely available for download and use.

Setting Up DWR

If you are familiar with the main JEE project structure, setting up DWR is relatively simple on any Java application server. To add Direct Web Remoting to any JEE project, there are three main steps. First, put the dwr.jar in the application path (this is usually the lib folder under the WEB-INF); second, add mapping to the special DWR Servlet in the main web.xml; and third, add a special dwr.xml descriptor file in the same folder as the web.xml file. The dwr.xml is the xml file that describes what objects and methods are “exposed” for the direct web remoting calls.

This is really all needed to set up the DWR on the server. The client-side is where the “exposed” methods are called. As you can see, the server setup does not require any changes to the existing Java code or server configuration code except extra mapping to just one Servlet.

Here is the directory structure in Eclipse:

The Servlet mapping in WEB-INF/web.xml can look like this:

The WEB-INF/dwr.xml can look like this, and I will follow up on this later.

On the client side, in the JSP or HTML page, calls to server side Java go though the AJAX JavaScript bridge. The JavaScript code for the bridge is in engine.js, util.js, and custom files generated dynamically corresponding to the exposed Java classes. Therefore, you need to include at least these files in your pages.

Ex.

<script src='/[WEBAPP-NAME]/dwr/engine.js'></script>
<script src='/[WEBAPP-NAME]/dwr/util.js'></script>

JavaScript to Java via AJAX

For the purposes of this article, I am using the Eclipse IDE and Tomcat application server, but any modern IDE and Java application server can work with the DWR. I set up a simple web application and several POJO classes, with one “exposed” for Direct Web Remoting through dwr.xml. When all correct JavaScipts are included on the page, the exposed class and its methods are “allowed” to be invoked from client-side JavaScript.

<allow>
   create creator="new" javascript="ItemManager">
   param name="class" value="model.ItemManager" />
   <include method="findById" />

In the client-side JavaScript, methods from ItemManager will be invoked asynchronously by using AJAX.

For example:

ItemManager.findById(handleItem, 1);

Note that the second parameter is the ID, and the first is a callback function that will be invoked when the response comes back with the data from the server.

The test client provided by the DWR Servlet also let you invoke methods, but it is a visual interface that hides the true method signature, and can only verify if the correct result returns. Nevertheless, it is a very useful tool (see next section).

Here is the flow diagram:

The parameters, such as ID, are JavaScript values that are sent to the server where only Java is executing. After the Java method returns data, the Java values are translated by DWR into JavaScript and are passed into Callback functions on the client side. There are some limitations as to what type of data can be converted from JavaScript to Java (and vice versa) as method parameters. The current version of DWR also has issues with overloaded Java methods. Because JavaScript does not support overloaded methods, a JavaScript file generated from a class that has overloaded methods will contain two methods, the second of which will replace the first.

Testing DWR

The DWR Servlet is very robust. It can output dynamic JavaScript code, it can correctly route Ajax calls, and it can even be used to debug the DWR logic. The debugging and testing functionality is conceptually similar to some implementations of Web Services test clients provided by different application sever vendors, such as BEA or IBM.

Recall that the DWR Servlet was mapped under the dwr pattern in the web.xml file.

<url-pattern>/dwr/*</url-pattern>

Client JSPs (or HTML files) can request dynamic JavaScript from the server by referencing this name in the path.

Also, recall that in the dwr.xml file there is a definition to expose ItemManager class.

allow>
   <create creator="new" javascript="ItemManager">
   param name="class" value="model.ItemManager" />

To use this object and its methods on the client page, DWR exposes a corresponding JavaScript file generated dynamically, when the client requests a specially defined URL from the server (via the dwr pattern path). The Servlet will generate and output this file on the fly.

The general format for the dynamic address is:

/[WEBAPP-NAME]/[MAPPING-NAME]/interface/[CLASS-NAME].js'

In the <script> tag, this address is set as the src attribute’s value. For example:

<script type='text/javascript'
src='/[WEBAPP-NAME]/dwr/interface/ItemManager.js'></script>

Including this in your page is perfectly valid and if you call this address directly, you will see the actual JavaScript code, even though this file does not exist on the server.

If you want to debug/test the DWR calls, the DWR Servlet needs to be in debug mode in the web.xml file. To enable debug, set the parameter for debug to true. Note that this is probably not desirable in production because it shows all available methods of the object to the client.

<init-param>
   <param-name>debug</param-name>
   <param-value>true</param-value>
</init-param>

To see the test client point your browser to