DWR Config

 

Getting Started with DWR

There are several ways to get started with DWR. We recommend the following:

• Download the dwr.war file and look/study the examples.
• Start integrating DWR in your application by following the 5 easy steps outlined below.
• Once DWR is up and running learn how to write JavaScript for DWR.

 

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. Install the Commons Logging JAR file

DWR has one dependency on Commons Logging. Download the commons-logging.jar and place it in the WEB-INF/lib directory of your webapp.

3. Add the DWR servlet definition and mapping to your application's web.xml

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>

4. Create the DWR configuration file (dwr.xml)

Create a new file in the WEB-INF (alongside web.xml) directory named dwr.xml.

A simple way to start is with something like this:

<!DOCTYPE dwr PUBLIC
    "-//GetAhead Limited//DTD Direct Web Remoting 3.0//EN"
    "http://getahead.org/dwr/dwr30.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>

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 one restriction:

• 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 in JavaScript but not Java.

Visit the dwr.xml documentation for a detailed description of the dwr.xml file, creators andconverters.

5. Take DWR for a test drive!

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 4. Having followed a link you should see an index of all the methods ready for calling. These pages are dynamically generated examples of what you can do using DWR.

Kick the tyres and have a look around.

How to make use of this from your web application

We have a whole section on writing Javascript with DWR, and 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.

Next Step: Learn about writing Javascript that interacts with DWR.

What if it doesn't work?

We have a page containing troubleshooting advice and common problems and their fixes. This is the first place to look.