The dwr.xml file is the standard way to configure DWR. By default you need to put it in the WEB-INF folder alongside web.xml.
In addition to this documentation here there is also a DTD for dwr.xml and a reference section that is generated by DTDDoc.
dwr.xml has the following structure:
<!DOCTYPE dwr PUBLIC
"-//GetAhead Limited//DTD Direct Web Remoting 3.0//EN"
"http://directwebremoting.org/schema/dwr30.dtd">
<dwr>
<!-- init is only needed if you are extending DWR -->
<init>
<creator id="..." class="..."/>
<converter id="..." class="..."/>
</init>
<!-- without allow, DWR isn't allowed to do anything -->
<allow>
<filter class="..."/>
<create creator="..." javascript="..."/>
<convert converter="..." match="..."/>
</allow>
<!-- you may need to tell DWR about method signatures -->
<signatures>
...
</signatures>
</dwr>
Some terminology worth understanding - parameters are converted, but the remoted beans are created. So if you have a bean A with a method A.blah(B) then you need a creator for A and a converter for B.
The 'allow' section defines which classes DWR can create and convert, and the global filters to use. This section is required for DWR to function - without it DWR is not allowed to do anything.
Each class which we intend to execute methods on, needs a <create ...> entry. There are several types of creator. The most commonly used creators are the New creator specified with the 'new' keyword or the Spring framework creator specified with the 'spring' keyword. For more information, see the Creator documentation.
We need to ensure that all the parameters can be converted. Many of the types provided by the JDK are converted by DWR automatically for you, but you need to give DWR permission to convert your own code. Generally this means that JavaBean parameters will need a <convert ...> entry.
By default all of the following are converted for you without further declaration:
For details on how to convert your own JavaBeans and other parameters see the Converter documentation.
Filters are a way to take some action either before, or after a server call, or to prevent the call from happening at all. For more information, see the Filter documentation.
The optional init section declares the classes that can be used to create beans to remote and the classes that can be used to convert beans in the marshalling process. For most cases you will not need to use it. If you wish to define a new Creator [JavaDoc] or Converter [JavaDoc] it needs to be declared here, but do double-check on the ones that are currently available first.
Having an entry in the init section just tells DWR about the existence of the class and gives it some basic detail about how it works. It does not bring it into use. In this way it is a bit like an import statement in Java. Most classes must be imported before use, but just having an import does not mean that the class is being used. Each creator and converter has an id attribute to allow it to be referred to later on.
DWR uses reflection to find out what types it should use in the conversion process. Sometimes the type information is not available, in which case you can type the method signatures in here to give it a hint. See the signatures section for more detail.
There can be more than one dwr.xml file (see the web.xml documentation for more details). The entries in each are added together. This ability is used by DWR to load the basic config file to get everyone started.
We can get a good introduction to dwr.xml files by looking at the standard dwr.xml file that everyone gets for free in the dwr.jar.