The Creators

The create element in your dwr.xml file has the following structure.

<allow>
  <create creator="..." javascript="..." scope="...">
    <param name="..." value="..."/>
    <auth method="..." role="..."/>
    <exclude method="..."/>
    <include method="..."/>
  </create>
  ...
</allow>

Most of these elements are optional - All you really need is to specify a creator and a JavaScript name.

The creator attribute is required - it specifies which creator will be used.

The following Creators are available in DWR:

new: Which uses the Java 'new' operator.
none: This does not create objects. See below for why. (v1.1+)
scripted: Uses a scripting language like BeanShell or Groovy via BSF.
spring: Gives access to beans through the Spring Framework.
jsf: Uses objects from JSF. (v1.1+)
struts: Uses struts FormBeans. (v1.1+)
pageflow: Gives access to a PageFlow from Beehive or Weblogic. (v1.1+)
ejb3: An experimental Creator to give access to EJB3 session beans. This code should not be seen as production quality until it has undergone more testing, and has an official maintainer. (v2.0+)

Should you need to write your own creator, you must register it using the <init> section.

The javascript attribute gives your newly created object a name in the browser. You should avoid using JavaScript reserved words.

The scope attribute is largely the same as the scope attribute as defined by the servlet spec. It allows you to specify what a bean is available to. The options are "application", session, "request", "page" and an additional scope "script". These first 4 of these values should be familiar to Servlet and JSP developers. "script" scope allows you to have something similar to an HTTP session that is tied to an ID in a page rather than in a cookie.

The scope attribute is optional. It defaults to "page".

The param element is used by the various creators for specific bits of configuration. For example the 'new' creator needs to be told what type of object to call 'new' on. The parameters that are available to each creator are specified in the documentation for that creator. See the list above for links.

The include and exclude elements allow a creator to restrict access to class methods. A Creator should specify EITHER a list of include elements (which implies that the default policy is denial) OR a list of exclude elements (which implies that the default policy is to allow access)

For example to deny access to all methods in some class except for the setWibble() method you should put the following into your dwr.xml

<create creator="new" javascript="Fred">
  <param name="class" value="com.example.Fred"/>
  <include method="setWibble"/>
</create>

The default visibility is that having added a class to a 'create' element, all its methods are accessible.

The auth element allows you to specify a J2EE role level for further access control checking:

<create creator="new" javascript="Fred">
  <param name="class" value="com.example.Fred"/>
  <auth method="setWibble" role="admin"/>
</create>

The 'none' Creator

The none creator does not do any object creation - it makes the assumption that you don't need one. This might be true for 2 reasons.

You might be using a scope other than "page" (see above) and have arranged to pre-populate the scope with the given object. In this case no object creation is required.

Alternatively the method to call is static in which case no object is required. DWR does a check for static methods before deciding if it needs to call the creator.

For both of these options you will need a param element - "class". This tells DWR what type it is working on.

Using static methods

DWR does a check before calling any Creators to see if the method to be called is static. If it is then the Creator is not called. Clearly this logic will work with any creator, however the 'null' Creator is easiest to configure.

Using Singletons

The best way to handle singletons is to create an instance of the object using BeanShell and BSF. See the section on the 'Scripted' Creator for more details.

Other Creators

We have occasional requests for new creators, the most common is for an EjbCreator. The best place to discuss new creators is the DWR mailing list.

DWR and HttpSessionBindingListeners

One subtlety about the way the DWR 1.x stores created beans is that it re-calls the corresponding setAttribute() method for every request. That is, if your bean has been given session lifetime in dwr.xml, session.setAttribute(yourBean) will be invoked everytime you invoke a method on that bean. This seems innocuous enough, however, if you're attempting to use servlet events, say, by way of the HttpSessionBindingListener interface then you'll see valueBound and valueUnbound events for every call, rather than only when your bean is created and when the session expires, as you might expect.

DWR 2 only calls setAttribute() when it first creates the object.

Direct Web Remoting