This chapter shows you how to use Web Flow in a Portlet environment. Web Flow has full support for JSR-168 portlets. 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. The configuration for a portlet depends on the portlet container used. The booking-portlet-mvc and booking-portlet-faces sample application are both configured to use Apache Pluto, the JSR-168 reference implementation. In general the configuration requires adding a servlet mapping in the web.xml file to dispatch request to the portlet container. swf-booking-mvc org.apache.pluto.core.PortletServlet portlet-name swf-booking-mvc 1 swf-booking-mvc /PlutoInvoker/swf-booking-mvc ]]> The portlet.xml configuration is a standard portlet configuration. The portlet-class needs to be set along with a pair of init-params. Setting the expiration-cache to 0 is recommended to force Web Flow to always render a fresh view. ... org.springframework.web.portlet.DispatcherPortlet contextConfigLocation /WEB-INF/web-application-config.xml viewRendererUrl /WEB-INF/servlet/view 0 ... ]]> The only supported mechanism for bridging a portlet request to Web Flow is via 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 any 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. Spring Portlet MVC provides a rich set of methods to map portlet requests. Complete documentation of the available methods 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. ]]> A FlowHandlerAdapter converts the handler mappings to the flow handlers. The flow executor is required as a constructor argument. ]]> In a portlet environemnt, alwaysRedirectOnPause must be set to false. If not turned off, the initial view will fail to render. ]]> 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. ViewRendererServlet org.springframework.web.servlet.ViewRendererServlet ViewRendererServlet /WEB-INF/servlet/view ]]> 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. 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. The Portlet API only allows redirects to be requested from an action request. Because views are rendered on the render request, views and view-states cannot trigger a redirect. 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. One way to start the new flow is to create a URL targeting the mode without the execution key. Web Flow supports JSF as the view technology for a portlet. However, a jsf-portlet bridge (JSR-301) must be provided. At the time of this writing, no feature complete jsf-portlet bridge exists. Some of the existing bridge implementations may appear to work, however, strange side effect may occur. JSF portlets are considered experimental at this time.