18.2 The DispatcherPortlet

18.2 The DispatcherPortlet
Prev	18. Portlet MVC Framework	Next

18.2 The `DispatcherPortlet`

Portlet MVC is a request-driven web MVC framework, designed around a portlet that dispatches requests to controllers and offers other functionality facilitating the development of portlet applications. Spring's DispatcherPortlet however, does more than just that. It is completely integrated with the Spring ApplicationContext and allows you to use every other feature Spring has.

Like ordinary portlets, the DispatcherPortlet is declared in the portlet.xml of your web application:

<portlet>
    <portlet-name>sample</portlet-name>
    <portlet-class>org.springframework.web.portlet.DispatcherPortlet</portlet-class>
    <supports>
        <mime-type>text/html</mime-type>
        <portlet-mode>view</portlet-mode>
    </supports>
    <portlet-info>
        <title>Sample Portlet</title>
    </portlet-info>
</portlet>

The DispatcherPortlet now needs to be configured.

In the Portlet MVC framework, each DispatcherPortlet has its own WebApplicationContext, which inherits all the beans already defined in the Root WebApplicationContext. These inherited beans can be overridden in the portlet-specific scope, and new scope- specific beans can be defined local to a given portlet instance.

The framework will, on initialization of a DispatcherPortlet, look for a file named [portlet-name]-portlet.xml in the WEB-INF directory of your web application and create the beans defined there (overriding the definitions of any beans defined with the same name in the global scope).

The config location used by the DispatcherPortlet can be modified through a portlet initialization parameter (see below for details).

The Spring DispatcherPortlet has a few special beans it uses, in order to be able to process requests and render the appropriate views. These beans are included in the Spring framework and can be configured in the WebApplicationContext, just as any other bean would be configured. Each of those beans is described in more detail below. Right now, we'll just mention them, just to let you know they exist and to enable us to go on talking about the DispatcherPortlet. For most of the beans, defaults are provided so you don't have to worry about configuring them.

Table 18.1. Special beans in the WebApplicationContext

Expression	Explanation
handler mapping(s)	(Section 18.5, “Handler mappings”) a list of pre- and post-processors and controllers that will be executed if they match certain criteria (for instance a matching portlet mode specified with the controller)
controller(s)	(Section 18.4, “Controllers”) the beans providing the actual functionality (or at least, access to the functionality) as part of the MVC triad
view resolver	(Section 18.6, “Views and resolving them”) capable of resolving view names to view definitions
multipart resolver	(Section 18.7, “Multipart (file upload) support”) offers functionality to process file uploads from HTML forms
handler exception resolver	(Section 18.8, “Handling exceptions”) offers functionality to map exceptions to views or implement other more complex exception handling code

When a DispatcherPortlet is setup for use and a request comes in for that specific DispatcherPortlet, it starts processing the request. The list below describes the complete process a request goes through if handled by a DispatcherPortlet:

The locale returned by PortletRequest.getLocale() is bound to the request to let elements in the process resolve the locale to use when processing the request (rendering the view, preparing data, etc.).
If a multipart resolver is specified and this is an ActionRequest, the request is inspected for multiparts and if they are found, it is wrapped in a MultipartActionRequest for further processing by other elements in the process. (See Section 18.7, “Multipart (file upload) support” for further information about multipart handling).
An appropriate handler is searched for. If a handler is found, the execution chain associated with the handler (pre- processors, post-processors, controllers) will be executed in order to prepare a model.
If a model is returned, the view is rendered, using the view resolver that has been configured with the WebApplicationContext. If no model is returned (which could be due to a pre- or post-processor intercepting the request, for example, for security reasons), no view is rendered, since the request could already have been fulfilled.

Exceptions that might be thrown during processing of the request get picked up by any of the handler exception resolvers that are declared in the WebApplicationContext. Using these exception resolvers you can define custom behavior in case such exceptions get thrown.

You can customize Spring's DispatcherPortlet by adding context parameters in the portlet.xml file or portlet init-parameters. The possibilities are listed below.

Table 18.2. DispatcherPortlet initialization parameters

Parameter	Explanation
`contextClass`	Class that implements `WebApplicationContext`, which will be used to instantiate the context used by this portlet. If this parameter isn't specified, the `XmlPortletApplicationContext` will be used.
`contextConfigLocation`	String which is passed to the context instance (specified by `contextClass`) to indicate where context(s) can be found. The String is potentially split up into multiple Strings (using a comma as a delimiter) to support multiple contexts (in case of multiple context locations, of beans that are defined twice, the latest takes precedence).
`namespace`	The namespace of the `WebApplicationContext`. Defaults to `[portlet-name]- portlet`.
`viewRendererUrl`	The URL at which `DispatcherPortlet` can access an instance of `ViewRendererServlet` (see Section 18.3, “The ViewRendererServlet”).