Reference to DWR entries in WEB-INF/web.xml
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.
Configuring DWR
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.
Remoting (JSONP) Parameters |
|
jsonpEnabled | |
---|---|
Version: | 3.0RC2 |
Default: | false |
Notes: | Set to true to enable DWR's JSONP remoting. |
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. |
generateDtoClasses | |
Version: | 2.0 |
Default: | interface |
Notes: | Controls whether or not DWR should generate script for class mappings - see Mapping Java classes to JavaScript classes. Defaults to interface which means DWR will add script for the mappings to each generated interface script. The parameter may be set to an empty string (to disable all class generation), to a single option (to generate classes in one location), or to a comma delimited list of options (to generate classes in multiple locations).
Options include:
|
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. |
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. |
normalizeIncludesSessionID | |
Version: | 3.0 RC2 |
Default: | false |
Notes: | (See notes above on welcomeFiles) Normally Reverse Ajax considers pages with differing session id's (if appended to the query string - ';jsessionid') to be the same page. Setting normalizeIncludesSessionID to true will make Reverse Ajax take the appended session id 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. |
The 'About' URL
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>
Officially Undocumented Parameters
The following init-params officially don't exist, but could be of use to people wishing to experiment with DWR.
- allowImpossibleTests: See DefaultRemoter (and others) to allow debug pages to generate tests for methods that should fail.
- exposeInternals: See DefaultAccessControl to allow DWR to marshall it's own classes.
- scriptSessionCheckTime: See DefaultScriptSessionManager to alter how often we check for timed-out ScriptSessions.
- initApplicationScopeCreatorsAtStartup: Create application scope beans as they are registered rather than when they are first used.
- scriptTagProtection: The reply prefix used to defeat script tag data theft. Defaults to '
throw 'crossDomainSessionSecurity is on.';
' - url:/some/url: See ContainerUtil to control how DWR handles the various internal URLs that it controls.