Configuring DWR - dwr.xml
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.
Creating a dwr.xml file
dwr.xml has the following structure:
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:
- All primitive types, boolean, int, double, etc.
- The Class based versions of the these Boolean, Integer, etc.
- java.util.Date and the 3 SQL derivatives
- arrays of the above
- Collections (Lists, Sets, Maps, Iterators, etc) of the above
- DOM objects (like Element and Document) from DOM, XOM, JDOM and DOM4J
- BLOBs like byte, java.io.InputStream, java.awt.image.BufferedImage or org.directwebremoting.io.FileTransfer can be downloaded by browsers, or displayed as images.
- Thrown instances of org.directwebremoting.io.DwrConvertedException are automatically passed to the client.
- Server-side versions of the TIBCO GI CDF Document: jsx3.xml.CdfDocument.
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.
Multiple dwr.xml Files
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.