Building a DWR Remote Proxy
This section should not be used as a tutorial on building DWR applications. It assumes that the reader has some familiarity with DWR. For further information including tutorials on this technology visit the DWR home page at www.directWebremoting.com. For our example we'll build a simple Web page with a Dojo ComboBox control that can be used to select a country. This ComboBox control will be "autocomplete"-enabled. As the user begins to type the name of a country the control will display a filtered list of country names that match the input.

First, we'll write a simple JavaBean that represents a country object as in Listing 1. The countryName attribute of this object will be used for filtering the options displayed by the ComboBox. We will also write a simple data access object named CountryDAO as in Listing 2 that can be used to get the list of all countries. (The implementation of this class is left to the reader.) This CountryDAO will be presented by DWR as a Remote Proxy that can be accessed by JavaScript on the browser. Listing 3 shows the DWR configuration required to do this.

A JavaScript on the browser should now be able to get the list of countries using the code snippet shown in Listing 4.

Building a DOJO Data Store
Now that we have a DWR remote proxy, let's build a Dojo data store that provides access to the list of countries. This section assumes some familiarity with Dojo, including classes and mixins. For more information on this toolkit read the Book of Dojo at www.dojotoolkit.org/book/dojo-book-1-0.

The Dojo.data package consists of a number of separate APIs that data stores can use. To keep our exercise simple we'll implement dojo.data.api.Read, which can read data items and their attributes.

Let's start with a shell that defines some essentials of a data store. Listing 5 shows a Dojo class named DWRReadStore. Data stores must declare the APIs they implement through a function called getFeatures. Our data store implements dojo.data.api.Read. Dojo widgets don't use data stores directly. Instead they use a mixin named simpleFetch to access data from a store. We'll mix dojo.data.util.simpleFetch into our data store. This requires that we provide a function named _fetchItems that we'll flesh out in subsequent steps.

Now that we have a basic (and essentially useless) data store we'll define some input parameters to the constructor of this class. The data store requires a reference to the JavaScript function generated by DWR - CountryDAO.getCountries. We'll pass a reference to this function to the constructor of the data store. In addition, we'll also initialize a few variables that will be used later. Listing 6 shows the changes to the constructor.

The next step is to implement the _fetchItems function. As mentioned _fetchItems is inherited from the simpleFetch mixin. This function takes three arguments, two of which are callback functions to be invoked in the case of success or failure. The first argument is a request object that encapsulates a number of input parameters from the caller. The two that should be of interest to us are "query," which is an associative array of filter parameters, and queryOptions. We'll examine how these parameters are used in the following section.

The _fetchItems function will be implemented as a two-step process. The first step will be to fetch data from the server if it has not already been loaded. This data will be cached to reduce the number of trips to the server. The second step will be to apply any necessary filters on the loaded data before returning it to the caller. Listing 7 shows the implementation of this function with simple data caching.

At this point we have a working data store. But, this data store always returns the entire data set and does not take into consideration any filter parameters supplied by the caller. We will now add the logic for handling data filtering (see Listing 8).

Finally, we will add the getValue function as in Listing 9. This function is defined in the Read API and is used by data consumers to obtain the value for any attribute of an item. In our example, the caller may use this function to get the value for the "countryName" attribute of the country item.

Using the Data Store with Dojo Widgets
At this point the data store is ready for Dojo widgets like ComboBox and FilteringSelect to use. Listing 10 shows a simple example of how this data store can be used with a Dojo widget. The use of this data store isn't significantly different from that of any other data store. It's initialized with a reference to the DWR function and applied to the widget. As the user types the name of a country into the ComboBox a dropdown list displays matching country names.

Conclusion
As demonstrated, DWR can be combined with the Dojo.data API to provide Web clients easy access to JavaBeans from a J2EE application server. DWR makes it easy to call Java classes from JavaScript, and Dojo provides a number of powerful widgets and other constructs that can be used to create a highly interactive user interface.

A number of enhancements can be made to this data store such as:

• Allow users to provide custom implementation for getValue by passing a reference to their own function that will be called by getValue.
• Add a mechanism to retry loading data from the server in case of a network error.
• Refresh cached data periodically, and so on.