com.ervacon.springframework.web.servlet.mvc.webflow
Class WebFlowController

java.lang.Object
  org.springframework.context.support.ApplicationObjectSupport
      org.springframework.web.context.support.WebApplicationObjectSupport
          org.springframework.web.servlet.support.WebContentGenerator
              org.springframework.web.servlet.mvc.AbstractController
                  com.ervacon.springframework.web.servlet.mvc.webflow.WebFlowController

All Implemented Interfaces:

org.springframework.context.ApplicationContextAware, org.springframework.web.servlet.mvc.Controller, org.springframework.beans.factory.InitializingBean

public class WebFlowController

extends org.springframework.web.servlet.mvc.AbstractController

implements org.springframework.beans.factory.InitializingBean

Concrete controller implementation that uses a web flow to handle client requests. For more details on how to define and use web flows, consult the package documentation and the web flow DTD.

This controller requires an HTTP session to keep track of flow state. So it will force the "requireSession" attribute defined by the AbstractController to true.

This controller recognizes the following request parameters:

name	value description
_flowId	The id of a previously started flow. When not present in the request, a new flow will be started.
_flowName	The name of the flow that should be started, which should be the name of a bean defined in the application context associated with this controller. When not present in the request, the value of the "webFlowName" property of the controller will be used.
_currentState	State of the flow in which the event should be executed. This is not used when starting a new flow. For an existing flow, it is optional. This parameter can be used to freely jump around in a flow: you are not restricted to the actual current state. Using it can also make flow navigation more robust when dealing with the browser Back button.
_event	Event that will be triggered in the current state of the flow. This is required when accessing an existing flow and not used when starting a new flow.

The following values will be exposed to the view via the model:

key	value description
flowId	The id of the executing flow. This can be used by the view to create links that point to this same flow. Actions can also use this value, e.g. to obtain the flow memento stack from the HTTP session (see WebFlowMementoStack). However, make note that the controller can only expose the flow id in the model of the top-level flow, that is, the flow started by the controller. If you need flow id in an action executed by a sub flow, you need to include the appropriate mapping specifications to map the flow id to that sub flow!
currentState	The current state of the flow.

Note that the keys used in the model can be configured using the "flowIdModelName" and "currentStateModelName" properties.

Workflow:

1. When a request comes in, the controller attempts to obtain a flow id from the request.
2. If no flow id is found, a new flow will be started which results in a model and view to display. The name of the flow to start is obtained from the "_flowName" request parameter or the "webFlowName" property as a fallback value.
3. If a flow id is found, the controller aquires the state (memento) of that flow from the HTTP session. It then continues this flow from its current state (or the state specified in the "_currentState" request parameter) using the event specified in the "_event" request parameter. This results in a model and view to display.
4. The "flowId" and "currentState" values are made available to the view in the model and both are returned to the DispatcherServlet for rendering.

Exposed configuration properties:

name	default	description
webFlowName	null	Name of the web flow that is used by this controller, which should be the name of a bean defined in the application context associated with this controller. We need the name of the flow and not the actual flow object since we must be able to reaquire a reference to the flow object at any moment, e.g. when returning from a sub flow. This flow name can possibly be overruled by a "_flowName" request parameter.
parameterExtractor	RPVPR	Parameter extractor used to extract the value of the "_flowId", "_flowName", "_event" and "_currentState" parameters from the incoming HTTP request.
flowIdModelName	flowId	The flow id will be exposed to the view using this key in the model.
currentStateModelName	currentState	The current state will be exposed to the view using this key in the model.

This class provides several extension hook methods to fine tune its behaviour in a subclass.

Author:

Erwin Vervaet

See Also:

WebFlow, ParameterExtractor

Field Summary

static java.lang.String	CURRENT_STATE_MODEL_NAME Key of the current state in the model exposed to the view.
static java.lang.String	FLOW_ID_MODEL_NAME Key of the flow id in the model exposed to the view.
static java.lang.String	PARAM_CURRENT_STATE Name of the request parameter that holds the current state of the flow.
static java.lang.String	PARAM_EVENT Name of the request parameter that specifies the event to trigger.
static java.lang.String	PARAM_FLOW_ID Name of the request parameter that holds the id of a previously started flow.
static java.lang.String	PARAM_FLOW_NAME Name of the request parameter that holds the name of the flow that should be started.

Fields inherited from class org.springframework.web.servlet.support.WebContentGenerator

HEADER_CACHE_CONTROL, HEADER_EXPIRES, HEADER_PRAGMA, METHOD_GET, METHOD_POST

Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

logger

Constructor Summary

WebFlowController()
Create a new web flow controller.

Method Summary

void	afterPropertiesSet()
protected WebFlowMementoStack	createMementos(java.lang.String flowName, java.lang.String id) Create a new memento stack for given web flow with given id.
protected void	deleteMementos(javax.servlet.http.HttpServletRequest request, java.lang.String id) Delete the web flow mementos stored in the HTTP session associated with given request using given id.
protected java.lang.String	generateId() Generate a pseudo unique id for a flow.
java.lang.String	getCurrentStateModelName() Get the key of the current state value in the model.
java.lang.String	getFlowIdModelName() Get the key of the flow id value in the model.
protected java.util.Map	getModelInputData(javax.servlet.http.HttpServletRequest request) Create a map of input data for a flow model.
protected java.lang.String	getParameter(javax.servlet.http.HttpServletRequest request, java.lang.String paramName) Get a named parameter from the request.
ParameterExtractor	getParameterExtractor() Get the parameter extractor used by the controller.
protected WebFlow	getWebFlow(java.lang.String flowName) Helper method to get an actual web flow object using a name.
java.lang.String	getWebFlowName() Get the name of the web flow executed by this controller.
protected org.springframework.web.servlet.ModelAndView	handleRequestInternal(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
protected WebFlowMementoStack	loadMementos(javax.servlet.http.HttpServletRequest request, java.lang.String id) Load the mementos stored in the HTTP session associated with given request using given id.
protected void	saveMementos(javax.servlet.http.HttpServletRequest request, java.lang.String id, WebFlowMementoStack mementos) Save given web flow mementos in the HTTP session associated with given request using given id.
void	setCurrentStateModelName(java.lang.String currentStateModelName) Set the key of the current state value in the model.
void	setFlowIdModelName(java.lang.String flowIdModelName) Set the key of the flow id value in the model.
void	setParameterExtractor(ParameterExtractor parameterExtractor) Get the parameter extractor used by the controller.
void	setWebFlowName(java.lang.String webFlowName) Set the name of the web flow executed by this controller.

Methods inherited from class org.springframework.web.servlet.mvc.AbstractController

handleRequest, isSynchronizeOnSession, setSynchronizeOnSession

Methods inherited from class org.springframework.web.servlet.support.WebContentGenerator

applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, checkAndPrepare, getCacheSeconds, getSupportedMethods, isRequireSession, isUseCacheControlHeader, isUseExpiresHeader, preventCaching, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseExpiresHeader

Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

getServletContext, getTempDir, getWebApplicationContext, isContextRequired

Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

getApplicationContext, getMessageSourceAccessor, initApplicationContext, requiredContextClass, setApplicationContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PARAM_FLOW_ID

public static final java.lang.String PARAM_FLOW_ID

Name of the request parameter that holds the id of a previously started flow. When not present in the request, a new flow will be started.

See Also:

Constant Field Values

PARAM_FLOW_NAME

public static final java.lang.String PARAM_FLOW_NAME

Name of the request parameter that holds the name of the flow that should be started. When not present in the request, the value of the "webFlowName" property of the controller itself will be used.

See Also:

Constant Field Values

PARAM_CURRENT_STATE

public static final java.lang.String PARAM_CURRENT_STATE

Name of the request parameter that holds the current state of the flow. This is optional. When not specified, the current state will be obtained from the flow memento.

See Also:

Constant Field Values

PARAM_EVENT

public static final java.lang.String PARAM_EVENT

Name of the request parameter that specifies the event to trigger.

See Also:

Constant Field Values

FLOW_ID_MODEL_NAME

public static final java.lang.String FLOW_ID_MODEL_NAME

Key of the flow id in the model exposed to the view.

See Also:

Constant Field Values

CURRENT_STATE_MODEL_NAME

public static final java.lang.String CURRENT_STATE_MODEL_NAME

Key of the current state in the model exposed to the view.

See Also:

Constant Field Values

Constructor Detail

WebFlowController

public WebFlowController()

Create a new web flow controller.

The "cacheSeconds" property will default to 0, so no caching will be done.

Method Detail

getWebFlowName

public java.lang.String getWebFlowName()

Get the name of the web flow executed by this controller. This flow name can possibly be overruled by a PARAM_FLOW_NAME request parameter. This is the name of a bean in the application context associated with this controller.

setWebFlowName

public void setWebFlowName(java.lang.String webFlowName)

Set the name of the web flow executed by this controller. This flow name can possibly be overruled by a PARAM_FLOW_NAME request parameter. This is the name of a bean in the application context associated with this controller.

getParameterExtractor

public ParameterExtractor getParameterExtractor()

Get the parameter extractor used by the controller. Defaults to RequestParameterValueParameterExtractor.

setParameterExtractor

public void setParameterExtractor(ParameterExtractor parameterExtractor)

Get the parameter extractor used by the controller. Defaults to RequestParameterValueParameterExtractor.

getFlowIdModelName

public java.lang.String getFlowIdModelName()

Get the key of the flow id value in the model. Defaults to "flowId".

setFlowIdModelName

public void setFlowIdModelName(java.lang.String flowIdModelName)

Set the key of the flow id value in the model. Defaults to "flowId".

getCurrentStateModelName

public java.lang.String getCurrentStateModelName()

Get the key of the current state value in the model. Defaults to "currentState".

setCurrentStateModelName

public void setCurrentStateModelName(java.lang.String currentStateModelName)

Set the key of the current state value in the model. Defaults to "currentState".

afterPropertiesSet

public void afterPropertiesSet()
                        throws java.lang.Exception

Specified by:

afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean

Throws:

java.lang.Exception

handleRequestInternal

protected org.springframework.web.servlet.ModelAndView handleRequestInternal(javax.servlet.http.HttpServletRequest request,
                                                                             javax.servlet.http.HttpServletResponse response)
                                                                      throws java.lang.Exception

Throws:

java.lang.Exception

getWebFlow

protected WebFlow getWebFlow(java.lang.String flowName)

Helper method to get an actual web flow object using a name.

getParameter

protected java.lang.String getParameter(javax.servlet.http.HttpServletRequest request,
                                        java.lang.String paramName)

Get a named parameter from the request. Delegates to the configured parameter extractor.

generateId

protected java.lang.String generateId()

Generate a pseudo unique id for a flow. This id will be used to store flow state in the HTTP session, so the generated id should be unique for an entire HTTP session.

createMementos

protected WebFlowMementoStack createMementos(java.lang.String flowName,
                                             java.lang.String id)

Create a new memento stack for given web flow with given id.

getModelInputData

protected java.util.Map getModelInputData(javax.servlet.http.HttpServletRequest request)

Create a map of input data for a flow model. The data in the map returned by this method is put in the flow model of each top-level flow started by this controller.

The default implementation just returns an empty map. Subclasses can override this if needed, e.g. picking input data from given request.

loadMementos

protected WebFlowMementoStack loadMementos(javax.servlet.http.HttpServletRequest request,
                                           java.lang.String id)

Load the mementos stored in the HTTP session associated with given request using given id.

saveMementos

protected void saveMementos(javax.servlet.http.HttpServletRequest request,
                            java.lang.String id,
                            WebFlowMementoStack mementos)

Save given web flow mementos in the HTTP session associated with given request using given id.

deleteMementos

protected void deleteMementos(javax.servlet.http.HttpServletRequest request,
                              java.lang.String id)

Delete the web flow mementos stored in the HTTP session associated with given request using given id.