The starting point of a DWR application is writing your server-side object model. In this case, I start by writing a DAO to provide search capabilities on the product catalog datastore. CatalogDAO.java is a simple, stateless class with a zero-argument constructor. Listing 1 shows the signatures of the Java methods that I want to expose to Ajax clients:

/**
 * Returns a list of items in the catalog that have 
 *  names or descriptions matching the search expression
 * @param expression Text to search for in item names 
 *  and descriptions 
 * @return list of all matching items
 */
public List<Item> findItems(String expression);

/**
 * Returns the Item corresponding to a given Item ID
 * @param id The ID code of the item
 * @return the matching Item
 */
public Item getItem(String id);

Next, I need to configure DWR, telling it that Ajax clients should be able to construct a CatalogDAO and call these methods. I do this with the dwr.xml config file shown in Listing 2:

<!DOCTYPE dwr PUBLIC
  "-//GetAhead Limited//DTD Direct Web Remoting 1.0//EN"
  "http://www.getahead.ltd.uk/dwr/dwr10.dtd">
<dwr>
  <allow>
    <create creator="new" javascript="catalog">
      <param name="class" 
        value="developerworks.ajax.store.CatalogDAO"/>
      <include method="getItem"/> 
      <include method="findItems"/> 
    </create> 
    <convert converter="bean" 
      match="developerworks.ajax.store.Item">
      <param name="include" 
        value="id,name,description,formattedPrice"/>
    </convert>
  </allow>
</dwr>

The root element of the dwr.xml document is dwr. Inside this element is the allow element, which specifies the classes that DWR will remote. The two child elements of allow are create and convert.

The create element

The create element tells DWR that a server-side class should be exposed to Ajax requests and defines how DWR should obtain an instance of that class to remote. The creator attribute here is set to the value new, meaning that DWR should call the class's default constructor to obtain an instance. Other possibilities are to create an instance through a fragment of script using the Bean Scripting Framework (BSF), or to obtain an instance via integration with the IOC container, Spring. By default, when an Ajax request to DWR invokes a creator, the instantiated object is placed in page scope and therefore is no longer available after the request completes. In the case of the stateless CatalogDAO, this is fine.

The javascript attribute of create specifies the name by which the object will be accessible from JavaScript code. Nested within the create element, a param element specifies the Java class that the creator will create. Finally, include elements specify the names of the methods that should be exposed. Explicitly stating the methods to expose is good practice to avoid accidentally allowing access to potentially harmful functionality -- if this element is omitted, all of the class's methods will be exposed to remote calls. Alternately, you can use exclude elements to specify only those methods you wish to prevent access to.

The convert element

While creators are concerned with exposing classes and their methods for Web remoting, convertors are concerned with the parameters and return types of those methods. The role of the convert element is to tell DWR how to convert datatypes between their server-side Java object representation and serialized JavaScript representation, and vice versa.

DWR automatically mediates simple data types between Java and JavaScript representations. These types include Java primitives, along with their respective class representations, as well as Strings and Dates, arrays, and collection types. DWR can also convert JavaBeans into JavaScript representations, but for security reasons, doing so requires explicit configuration.

The convert element in Listing 2 tells DWR to use its reflection-based bean convertor for the Items returned by the exposed methods of CatalogDAO and specifies which of the Item's members should be included in the serialization. The members are specified using the JavaBean naming convention, so DWR will call the corresponding get methods. In this case, I'm omitting the numerical price field and instead including the formattedPrice field, which is currency-formatted ready for display.

At this point, I'm ready to deploy my dwr.xml to my Web application's WEB-INF directory, where the DWR servlet will pick it up. Before proceeding, however, it's a good idea to ensure that everything is working as expected.