Background

Webwork comes with a number of dispatchers to handle usage in different environments. A dispatcher is a central entry point to webwork's actions. Generally dispatchers are responsible for setting up the environment for the current request.

Note that in this context, a request is not necessarily a web request, it can be a remote request, or a local method call to webwork, as well as the common case of a web HTTP request.

Since dispatchers are the entry point into webwork, the internals of webwork and actions have no awareness of the dispatcher used. Thus there is no generic dispatcher interface, and it is entirely upto a particular dispatcher implementation to determine how it can be invoked and what it requires from the caller. Dispatchers can perform as much or as little up front set up as required.

The servlet dispatcher for example handles web requests, and is more involved than the other dispatchers available. A brief description of the available dispatchers follows.

Servlet Dispatcher

The ServletDispatcher is the default dispatcher for handling all web HTTP requests. It is implemented as a servlet, and all calls to webwork actions must pass through this dispatcher. This is done by specifying the ServletDispatcher servlet in the web application's web.xml descriptor, and all webwork actions (default of *.action) mapped to this dispatcher servlet.

When the dispatcher receives an incoming web request, the first step is to determine whether it is a multipart request with file attachments or not. This is done up front so actions do not have to handle parsing of multipart requests or have convoluted logic to pull request parameters based on the type of request. Once that is done, the dispatcher determines the name of the action requested based on the URL. Internally, the ServletDispatcher is a wrapper around GenericDispatcher, and simply adds extra handling for web invocation semantics.

Thus, once the action name has been determined via a web-specific method (URL), a GenericDispatcher is created for that action, and a generic ActionContext created from that dispatcher. Since this is a web specific dispatcher, the ServletActionContext is initialized and connected to the generic ActionContext.

Finally, the dispatcher initializes the value stack and executes the action to determine the view which is then displayed.

Generic Dispatcher

The GenericDispatcher is a dispatcher that is invocation agonistic. It's agonostic in the sense that it makes no assumptions regarding the pecularities of the invoker, and it does not perform any mappings from the invoker's environment to webwork's environment. It is invoked simply through a Java method call.

Once invoked, the dispatcher performs generic webwork setup. This includes creating an ActionContext, determining the action being invoked based on the action parameter specified by the invoker, and finally invoking the requested action. Since this dispatcher is view and invoker agnostic, it has no way of determining what a view means. So the result of the action invocation is a wrapper object (ActionResult) that contains a view name (for example, SUCCESS), as well as a List of the actions invoked and any exception that might have been thrown.

The generic dispatcher is useful in cases where it needs to be called outside of a web environment. For example, a java bean that runs within your web container but has no web semantics determining its behaviour might wish to use the generic dispatcher to invoke a webwork action.

Client Dispatcher

The ClientDispatcher is, as the name implies, a dispatcher for remote clients. It works in unison with a ClientServletDispatcher, and handles all the plumbing required for remote calls.

In terms of implementation, the client dispatcher opens up an HTTP connection to the remote ClientServletDispatcher, and serializes the action to be invoked to the server. The server receives the requested action and deserializes it, prepares the context and does all the setup required then invokes the action. The action result is serialized back to the client dispatcher, that in turn returns it to the caller.

All this happens serially, the client (for example, an applet or a swing application) creates the Action to be invoked, and invokes it on the ClientDispatcher that will return the result of the remote action invocation.

Test Dispatcher

The TestDispatcher is useful when constructing test cases. It does very little up front setup and allows the caller to specify input parameters alongside the action name, which most other dispatchers do not allow (with the obvious exception of the ServletDispatcher).