Dispatch Configurations

The <dispatch> element is used to define a dispatch configuration. It may appear either inside the <dispatches> element to define a global dispatch configuration or inside an <action> element to define a local dispatch configuration.

A dispatch configuration contains information about how to proceed after action invocation. It may either point to another action or to a resource path. It may also specify a custom dispatcher and whether to use redirection.

The <dispatch> element takes the following attributes:

• The name attribute - specifying the name of the dispatch configuration. Actions use this name to lookup a configuration in the pool of local and global dispatch configurations. Omitting the name attribute creates a "default" dispatch configuration whose name property is null.
• The action attribute, optionally in conjunction with the module attribute - to dispatch to another action; if the module attribute is omitted, the current module is assumed.
• The path attribute - to dispatch to that path; e.g., the path may be a context-relative. However, custom dispatchers may interpret this attribute in their own fashion.
• The redirect attribute - specifying to redirect the response, if set to true.
• The dispatcher attribute - specifying a custom dispatcher to be used; custom dispatchers are registered by plugins.

It is an error to specifying both, the action and path attributes. Furthermore, the module attribute is only permitted in conjunction with the action attribute.

The body of the <action> element may contain a set of <param> elements. Dispatchers may use parameters in their own way. However, the default dispatcher will append them as request parameters.

A dispatch configuration is reflected by the DispatchConfig interface, which defines methods to access the attribute values as well as the getParamConfig() method to lookup parameters by name.

The DispatchConfig interface is the result type of the action's execute() method. An action uses its action configuration, ActionConfig, to lookup a dispatch configuration by name, using the

public DispatchConfig findDispatchConfig(String name);

method. The default dispatch configuration can be accessed by specifying name null.

Examples

<dispatch name="foo" action="/bar"/>

<dispatch name="foo" module="other" action="/bar"/>

<dispatch name="foo" path="/WEB-INF/jsp/bar.jsp"/>

<dispatch name="foo" path="/WEB-INF/jsp/bar.jsp">
  <param name="mode" value="lazy"/>
</dispatch>

<dispatch name="foo" path="/jsp/bar.jsp" redirect="true"/>

<dispatch name="foo" path="http://calyxo.org" redirect="true"/>

<dispatch name="foo" dispatcher="xslt" path="/bar.xml">
  <param name="stylesheet" value="/WEB-INF/xsl/style.xsl"/>
</dispatch/>