The Creators

Creators are an integral part of DWR and are responsible for exposing the methods on Java classes to the client.

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 the creator and javascript attributes.

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

The following Creators are available in DWR:

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

The javascript attribute is required - it 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". The 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 static creator is the recommended approach for using Singletons.

An alernative approach 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.