The minimum possible additions to your web.xml, are simply those to declare the DWR servlet and the appropriate servlet mapping. So the least you can get away with looks something like this:
<servlet> <servlet-name>dwr-invoker</servlet-name> <servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>dwr-invoker</servlet-name> <url-pattern>/dwr/*</url-pattern> </servlet-mapping>
In addition to this there are several extra servlet parameters that are somewhere between important and vaguely useful. In DWR 3.0 all logging is done through the commons-logging API. Important log levels are documented in the logging section.
The standard mechanism for extending DWR is to use init-params. The most common init-param is to enable test mode. To use one of these parameters alter the <servlet> stanza above like this:
<servlet>
<servlet-name>dwr-invoker</servlet-name>
<servlet-class>org.directwebremoting.servlet.DwrServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>true</param-value>
</init-param>
</servlet>
DWR supports more init-params than those documented here, however un-documented init-params may be withdrawn without deprecation in future releases.
Security Parameters |
|
| allowGetForSafariButMakeForgeryEasier | |
|---|---|
| Version: | 2.0 |
| Default: | false |
| Notes: | Set to true to make DWR work in Safari 1.x (where a bug drops the bodies from POST requests). POST requests are slightly harder to forge, so enabling this reduces security slightly. |
| crossDomainSessionSecurity | |
| Version: | 2.0 |
| Default: | true |
| Notes: | Set to false to enable requests from other domains. Note that enabling this can be a significant security risk. See the Wikipedia notes on CSRF for more. Do not set this to false without understanding the consequences. |
| allowScriptTagRemoting | |
| Version: | 2.0 rc4 |
| Default: | true |
| Notes: | Set to true to enable Script Tag remoting. Note that enabling this can be a significant security risk. See the Wikipedia notes on CSRF for more. Do not set this to false without understanding the consequences. There are some cases where you will need to enable Script Tag remoting, but want to leave crossDomainSessionSecurity in place - particularly when you have an http based web page, and an https based DWR service. |
| debug | |
| Version: | 1.0 |
| Default: | false |
| Notes: | Set to true to enable the debug/test pages. |
| scriptSessionTimeout | |
| Version: | 2.0 |
| Default: | 1800000 (30 mins) |
| Notes: | How quickly do scriptSessions timeout? |
| maxCallCount | |
| Version: | 2.0rc2 and 1.1.4 |
| Default: | 20 |
| Notes: | What is the maximum number of calls that can be done in a single batch. (Helps prevent DoS attacks). |
Ajax Server Load Protection Parameters |
|
| activeReverseAjaxEnabled | |
| Version: | 2.0 RC3 |
| Default: | false |
| Notes: | Set to true to enable polling and comet. This can increase the load on your server although DWR does have mechanisms to prevent server overload. Was called pollAndCometEnabled before RC3 |
| pollAndCometEnabled | |
| Version: | 2.0 RC1 |
| Default: | false |
| Notes: | See activeReverseAjaxEnabled. |
| maxWaitingThreads | |
| Version: | 2.0 |
| Default: | 100 |
| Notes: | What is the maximium number of threads we keep waiting. We reduce the time within poll to reduce the load. (Only for use with servlet engines that do not support thread-dropping) |
| maxHitsPerSecond | |
| Version: | 2.0 |
| Default: | 40 |
| Notes: | What is the maximum number of hits we should get per second. We increase the poll time to compensate and reduce the load. (Only for use with servlet engines that do not support thread-dropping) |
Other Parameters |
|
| [Interface Name] | |
| Version: | 1.1 |
| Default: | The default implementation of the given interface |
| Notes: | DWR allows you to override parts of itself without needing to recompile. See the plug-ins documentation for more details. |
| ignoreLastModified | |
| Version: | 2.0 |
| Default: | false |
| Notes: | By default DWR supports Last-Modified/ETags to allow the server to say encourage client to request for resources less. Setting this to true disables this support. |
| scriptCompressed | |
| Version: | 1.1 - 2.0 |
| Default: | false |
| Notes: | From version 3.0, DWR automatically compresses output scripts in live mode (see the 'debug' init-param) and leaves them uncompressed in debug mode. The 'scriptCompressed' init-param is NOT required. DWR will use ShrinkSafe or the YUI compressor automatically if they are found in the classpath, otherwise a simpler built-in compressor will be used.
Prior to version 3 only the simpler compression was avaiable, and it required the 'scriptCompressed' init-param to be set to 'true'. There is an associated and officially undocumented parameter: compressionLevel which allows you to configure the types of compression that are attempted. See the source for org.directwebremoting.util.JavascriptUtil for more details. |
| sessionCookieName | |
| Version: | 2.0 |
| Default: | JSESSIONID |
| Notes: | DWR supports URL re-writing by examining the document location and extracting the current session id. Some servlet engines use non-standard cookie names. This parameter allows you to change the default. |
| welcomeFiles | |
| Version: | 2.0 |
| Default: | index.html, index.htm, index.jsp |
| Notes: | To enable DWR's ability to find users on a given page it must understand page aliases. The basic implementation reads web.xml looking for the <welcome-file-list> element, however this can be overridden either with this parameter or by creating a new implementation of org.directwebremoting.extend.PageNormalizer. |
| normalizeIncludesQueryString | |
| Version: | 2.0 RC3 |
| Default: | false |
| Notes: | (See notes above on welcomeFiles) Normally Reverse Ajax considers pages with differing query strings (the part of a URL after the ? and before the #) to be the same page. Sometimes (particularly with CMS sites) this is not the case. Setting normalizeIncludesQueryString to true will make Reverse Ajax take the query string into account. |
| overridePath | |
| Version: | 2.0 |
| Default: | null |
| Notes: | If your servlet engine is fronted by a webserver that alters the path the DWR may send requests back to the wrong destination. You can set an overridePath to be the new default. |
DWR handles a number of URLs; one of them is the 'about' URL which links to the DWR website. You can see an example of this in the copy of DWR that this website uses to host demos. To configure DWR to not display this URL, include the following init-param:
<init-param> <param-name>url:/about</param-name> <param-value>null</param-value> </init-param>
The following init-params officially don't exist, but could be of use to people wishing to experiment with DWR.
throw 'crossDomainSessionSecurity is on.';'