14. Portlet Integration
Prev |  | Next

## 14. Portlet Integration

## 14.1. Introduction

This chapter shows how to use Web Flow in a Portlet environment. Spring Web Flow requires Portlet API 2.0 to run with. The `booking-portlet-mvc` sample application is a good reference for using Web Flow within a portlet. This application is a simplified travel site that allows users to search for and book hotel rooms.

## 14.2. Configuring web.xml and portlet.xml

The configuration for a portlet depends on the portlet container used. The sample applications, included with Web Flow, are both configured to use Apache Pluto.

In general, the configuration requires adding a servlet mapping in the `web.xml` file to dispatch request to the portlet container.

    <servlet>
        <servlet-name>swf-booking-mvc</servlet-name>
        <servlet-class>org.apache.pluto.core.PortletServlet</servlet-class>
        <init-param>
            <param-name>portlet-name</param-name>
            <param-value>swf-booking-mvc</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>swf-booking-mvc</servlet-name>
        <url-pattern>/PlutoInvoker/swf-booking-mvc</url-pattern>
    </servlet-mapping>

The `portlet.xml` configuration is a standard portlet configuration. The `portlet-class` needs to be set along with a pair of `init-param`s. Setting the `expiration-cache` to `0` is recommended to force Web Flow to always render a fresh view.

    <portlet>
        ...
        <portlet-class>org.springframework.web.portlet.DispatcherPortlet</portlet-class>
        <init-param>
            <name>contextConfigLocation</name>
            <value>/WEB-INF/web-application-config.xml</value>
        </init-param>
        <init-param>
            <name>viewRendererUrl</name>
            <value>/WEB-INF/servlet/view</value>
        </init-param>
        <expiration-cache>0</expiration-cache>
        ...
    </portlet>

## 14.3. Configuring Spring

### 14.3.1. Flow Handlers

The only supported mechanism for bridging a portlet request to Web Flow is a `FlowHandler`. The `PortletFlowController` used in Web Flow 1.0 is no longer supported.

The flow handler, similar to the servlet flow handler, provides hooks that can:

- select the flow to execute

- pass input parameters to the flow on initialization

- handle the flow execution outcome

- handle exceptions

The `AbstractFlowHandler` class is an implementation of `FlowHandler` that provides default implementations for these hooks.

In a portlet environment the targeted flow id can not be inferred from the URL and must be defined explicitly in the handler.

    public class ViewFlowHandler extends AbstractFlowHandler {
        public String getFlowId() {
            return "view";
        }
    }

### 14.3.2. Handler Mappings

Spring Portlet MVC provides a rich set of methods to map portlet requests. Complete documentation is available in the Spring Reference Documentation.

The `booking-portlet-mvc` sample application uses a `PortletModeHandlerMapping` to map portlet requests. The sample application only supports `view` mode, but support for other portlet modes is available. Other modes can be added and point to the same flow as `view` mode, or any other flow.

    <bean id="portletModeHandlerMapping"
          class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
        <property name="portletModeMap">
            <map>
                <entry key="view">
                    <bean class="org.springframework.webflow.samples.booking.ViewFlowHandler" />
                </entry>
            </map>
        </property>
    </bean>

### 14.3.3. Flow Handler Adapter

A `FlowHandlerAdapter` converts the handler mappings to the flow handlers. The flow executor is required as a constructor argument.

    <bean id="flowHandlerAdapter"
          class="org.springframework.webflow.mvc.portlet.FlowHandlerAdapter">
        <constructor-arg ref="flowExecutor" />
    </bean>

## 14.4. Portlet Views

In order to facilitate view rendering, a `ViewRendererServlet` must be added to the `web.xml` file. This servlet is not invoked directly, but it used by Web Flow to render views in a portlet environment.

    <servlet>
        <servlet-name>ViewRendererServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.ViewRendererServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>ViewRendererServlet</servlet-name>
        <url-pattern>/WEB-INF/servlet/view</url-pattern>
    </servlet-mapping>

## 14.5. Portlet Modes and Window States

### 14.5.1. Window State

The Portlet API defined three window states: normal, minimized and maximized. The portlet implementation must decide what to render for each of these window states. Web Flow exposes the string value of the window state under `portletWindowState` via the request map on the external context.

    requestContext.getExternalContext().getRequestMap().get("portletWindowState");

    externalContext.requestMap.portletWindowState

### 14.5.2. Portlet Mode

The Portlet API defined three portlet modes: view, edit and help. The portlet implementation must decide what to render for each of these modes. Web Flow exposes the string value of the portlet mode under `portletMode` via the request map on the external context.

    requestContext.getExternalContext().getRequestMap().get("portletMode");

    externalContext.requestMap.portletMode

## 14.6. Using Portlets with JSF

Prior to version 2.1 of Spring Web Flow, support for JSF Portlets was considered experimental and relied on a Portlet Bridge for JSF implementation. Furthermore JSR-329 (the latest specification in this area), which targets Portlet API 2.0 and JSF 1.2 environments at the time of writing is not yet final causing portlet bridge implementations to also remain incomplete.

A closer comparison of Spring Web Flow and a Portlet Bridge for JSF shows the two have significant overlap. They both drive the JSF lifecycle and they both shield JSF from knowledge about Portlet action and render requests.

Considering all of the above, starting with version 2.2, Spring Web Flow provides support for JSF Portlets using its own internal Portlet integration rather than a Portlet Bridge for JSF. We believe this will provide value for Web Flow users by reducing the number of dependencies in what is already a fairly complex combination of technologies with specifications lagging behind.

What this practically means is the configuration required for JSF Portlets is very similar to what is alread documented in the rest of this chapter with the exception of Section 14.4, “Portlet Views”, which is not necessary with JSF.

Review the `swf-booking-portlet-faces` sample in the Web Flow distribution for a working JSF Portlets example with complete configuration details. The main thing you'll need to notice in addition to what has already been described in this chapter is the `faces-config.xml` configuration:

    <?xml version="1.0"?>
    <!DOCTYPE faces-config PUBLIC
      "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
      "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">

    <faces-config>
        <application>
            <view-handler>
                org.springframework.faces.webflow.application.portlet.PortletFaceletViewHandler
            </view-handler>
        </application>
    </faces-config>

## 14.7. Issues in a Portlet Environment

### 14.7.1. Redirects

The Portlet API only allows redirects to be requested from an action request. Because views are rendered on the render request, views and `view-state`s cannot trigger a redirect.

The `externalRedirect:` view prefix is a convenience for Servlet based flows. An `IllegalStateException` is thrown if a redirect is requested from a render request.

`end-state` redirects can be achieved by implementing `FlowHandler.handleExecutionOutcome`. This callback provides the `ActionResponse` object which supports redirects.

### 14.7.2. Switching Portlet Modes

The portlet container passes the execution key from the previous flow when switching to a new mode. Even if the mode is mapped to a different `FlowHandler` the flow execution will resume the previous execution. You may switch the mode programatically in your FlowHandler after ending a flow in an ActionRequest.

One way to start a new flow is to create a URL targeting the mode without the execution key.

Prev |  | Next
13. JSF Integration | Home | 15. Testing flows