DWR Quick Start Guide - SitePen, Inc.

SitePen DWR Support

Peace of Mind. Reduced Pain. Faster time to market. Check out our support services.

SitePen DWR Training

New to Dojo, DWR, Ajax, or Comet? Have us train your team!

DWR: Easy Ajax for Java

DWR is a RPC library which makes it easy to call Java functions from JavaScript and to call JavaScript functions from Java (a.k.a Reverse Ajax).

It has a large user-base, active mailing list and has been used in many projects including the Walmart shopping site and American Airlines flight booking site.

DWR has a number of features like call batching, marshalling of virtually any data-structure between Java and Javascript (including binary file uploading and downloading), exception handling, advanced CSRF protection and deep integration with several Java server-side technologies like Spring and Guice.

The first diagram shows how DWR can alter the contents of a selection list as a result of some Javascript event.

DWR Diagram

Reverse Ajax (available since DWR version 2.0) allows Java code running on the server to find out what clients are viewing certain pages, and to send to them JavaScript, generated either manually or using a Java API. These JavaScript generating APIs generally match a client-side APIs.

DWR Diagram

DWR consists of two main parts:

A Java Servlet running on the server that processes requests and sends responses back to the browser.
JavaScript running in the browser that sends requests and can dynamically update the webpage.

DWR works by dynamically generating Javascript based on Java classes. The code does some Ajax magic to make it feel like the execution is happening on the browser, but in reality the server is executing the code and DWR is marshalling the data back and forwards.

This method of remoting functions from Java to JavaScript gives DWR users a feel much like conventional RPC mechanisms like RMI or SOAP, with the benefit that it runs over the web without requiring web-browser plug-ins.

The DWR project is developing a method of automatically creating Java versions of JavaScript APIs which developers can use to control browsers from the server. A server-side version of the TIBCO GI library is currently in alpha release, and the DWR project aims to expand this to cover other client side APIs including the Dojo Toolkit, JQuery, YUI, Ext and others.

For details on how to get started with DWR see the getting started guide and download instructions.

Getting The Code

The following DWR download packages are available. If you are just getting started with DWR, the JAR download is probably the best place to start.

Development Release: Version 3

DWR version 3 is under heavy development, we have started to release preview versions. The latest preview release is DWR 3, milestone 1. DWR 3 supports JDK 1.4 using retroweaver, so you will need to download the dwr-jdk14.jar release for that platform.

Stable Release: Version 2.0.3

DWR 2.0.3 includes Reverse Ajax and a large number of other enhancements. For details of the changes see the release notes for DWR Version 2.


Download 	Version 2.0.3		Size
JAR File: 	dwr.jar			(489 KB)
WAR File: 	dwr.war			(2.14 MB)
Sources: 	dwr-2.0.3-src.zip	(20.78 MB)

Previous Stable Release: Version 1.1.4

For changes in version 1.1 since version 1.0 see the release notes for version 1.1 and the small list of bug fixes for 1.1.4. DWR version 1.x is no longer officially supported, and we encourage people to upgrade to the latest release.


Download 	Version 1.1.4 		Size
JAR File: 	dwr.jar 		(182 KB)
WAR File: 	dwr.war 		(202 KB)
Sources: 	dwr-1.1.4-src.zip  	(6.01 MB)

First Steps

There are two ways to get started with DWR, the easy way is to download the WAR file and have a look around, however this does not help you see how easily DWR integrates with your current web application, so the following 3 simple steps are recommended:

1. Install the DWR JAR file

Download the dwr.jar file. Place it in the WEB-INF/lib directory of your webapp. You'll probably have a set of jar files in there already.

2. Edit the config files

The following lines need to be added to WEB-INF/web.xml. The <servlet> section needs to go with the other <servlet> sections, and likewise with the <servlet-mapping> section.

<servlet>
  <servlet-name>dwr-invoker</servlet-name>
  <display-name>DWR Servlet</display-name>
  <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
  <init-param>
     <param-name>debug</param-name>
     <param-value>true</param-value>
  </init-param>
</servlet>

<servlet-mapping>
  <servlet-name>dwr-invoker</servlet-name>
  <url-pattern>/dwr/*</url-pattern>
</servlet-mapping>

If you are using DWR 1.x then the servlet-class line should contain the following: uk.ltd.getahead.dwr.DWRServlet. The 1.x version will still work with 2.x, but the new one is preferred.

Then create a dwr.xml file that lives in WEB-INF alongside web.xml. A simple way to start is with something like this:

<!DOCTYPE dwr PUBLIC
    "-//GetAhead Limited//DTD Direct Web Remoting 2.0//EN"
    "http://getahead.org/dwr/dwr20.dtd">

<dwr>
  <allow>
    <create creator="new" javascript="JDate">
      <param name="class" value="java.util.Date"/>
    </create>
    <create creator="new" javascript="Demo">
      <param name="class" value="your.java.Bean"/>
    </create>
  </allow>
</dwr>

Obviously, if you are using version 1.x the opening line will have 1.0 in place of 2.0 and 10 in place of 20.

The DWR config file defines what classes DWR can create and remote for use by JavaScript. In the example above we are defining 2 classes that are remoted and giving the classes names in JavaScript.

The new creator that we used above uses the public no-args constructor that all JavaBeans must have. It is also worth remembering that DWR has a few restrictions:

Avoid reserved JavaScript words; Methods named after reserved words are automatically excluded. Most JavaScript reserved words are also Java reserved words, so you won't be having a method called "try()" anyway. However the most common gotcha is "delete()", which has special meaning from JavaScript but not Java.
Overloaded methods can be involved in a bit of a lottery as to which gets called, so avoid overloaded methods.

3. Check localhost

Go to the following URL: http://localhost:8080/[YOUR-WEBAPP]/dwr/

You should see a page showing you the classes that you've selected in step 2. Having followed a link you should see an index of all the methods all ready for calling. These pages are dynamically generated examples of what you can do using DWR.

Kick the tyres and have a look around.

4. How to make use of this from your web application

There are a number of examples in the sidebar that demonstrate how to dynamically alter the text in web pages, update lists, manipulate forms and do live table editing. Each has a description of how it works.

Another way to get started is to look at the source from the pages that you just viewed:

Go to http://localhost:8080/[YOUR-WEBAPP]/dwr/ and click on you class
View source and find the line that executes the method that you are interested in.
Paste the text into an HTML or JSP page in your web-app.
Include links to the JavaScript files that make the magic happen:

<script src='/[YOUR-WEBAPP]/dwr/interface/[YOUR-SCRIPT].js'></script>
<script src='/[YOUR-WEBAPP]/dwr/engine.js'></script>

You can omit the /[YOUR-WEBAPP]/ section and use relative paths in your web pages if you wish.

For more information about how to write JavaScript that interacts with DWR see the scripting introduction.

5. Help, it doesn't work?!?

There is a great community available to help you with DWR. There is a collection of common problems and their solutions, an active DWR mailing list, and a DWR book.

DWR Commercial Support and other DWR Services are also available from SitePen.