org.springframework.webflow.executor.jsf
Class FlowPhaseListener

java.lang.Object
  extended by org.springframework.webflow.executor.jsf.FlowPhaseListener
All Implemented Interfaces:
java.io.Serializable, java.util.EventListener, javax.faces.event.PhaseListener

public class FlowPhaseListener
extends java.lang.Object
implements javax.faces.event.PhaseListener

JSF phase listener responsible for managing the FlowExecution object lifecycle in a JSF environment. This class handles restoring and saving a FlowExecution so other JSF artifacts that execute in different phases of the JSF lifecycle may access conversational state and utilize Web Flow navigation behavior.

A restored flow execution is placed in a holder that other JSF artifacts such as VariableResolvers, PropertyResolvers and NavigationHandlers may access during the request lifecycle. Once in the holder the execution is considered "restored" and referred to as the "current" flow execution for this request.

This phase listener implements the following algorithm:

Note about customization: since PhaseListeners managed directly by the JSF provider cannot be benefit from DependencyInjection, See Spring's DelegatingPhaseListenerMulticaster when you need to customize a FlowPhaseListener instance.

Author:
Colin Sampaleanu, Keith Donald, Jeremy Grelle
See Also:
Serialized Form

Nested Class Summary
static class FlowPhaseListener.DefaultViewIdMapper
          Standard default view id resolver which uses the web flow view name as the jsf view id
 
Field Summary
protected  org.apache.commons.logging.Log logger
          Logger, usable by subclasses.
 
Constructor Summary
FlowPhaseListener()
           
 
Method Summary
 void afterPhase(javax.faces.event.PhaseEvent event)
           
 void beforePhase(javax.faces.event.PhaseEvent event)
           
protected  FlowExecutionKeyStateHolder createFlowExecutionKeyStateHolder()
          Factory method that creates the state holder UI component that will track the flow execution key used for execution restoration during subsequent restore view phases.
protected  MutableAttributeMap createInput(ExternalContext context)
          Factory method that creates the input attribute map for a newly created FlowExecution.
 FlowExecutorArgumentHandler getArgumentHandler()
          Returns the argument handler used by this phase listener.
 org.springframework.binding.mapping.AttributeMapper getInputMapper()
          Returns the configured flow execution input mapper.
 javax.faces.event.PhaseId getPhaseId()
           
 ViewIdMapper getViewIdMapper()
          Returns the JSF view id resolver used by this phase listener.
protected  void handleFlowExecutionAccessException(FlowExecutionAccessException e, javax.faces.context.FacesContext context)
          Hook method to handle a thrown flow execution access exception.
protected  void prepareApplicationView(javax.faces.context.FacesContext facesContext, FlowExecutionHolder holder)
          Prepare the JSF view for rendering.
protected  void prepareResponse(JsfExternalContext context, FlowExecutionHolder holder)
          Prepare the appropriate JSF response (e.g.
protected  void restoreFlowExecution(javax.faces.context.FacesContext facesContext)
           
protected  void saveFlowExecution(JsfExternalContext context, FlowExecutionHolder holder)
          Updates the current flow execution in the repository.
protected  void sendRedirect(java.lang.String url, javax.faces.context.FacesContext context)
          Helper method to issue a redirect in a JSF environment properly.
 void setArgumentHandler(FlowExecutorArgumentHandler argumentHandler)
          Sets the handler for arguments needed by this phase listener to restore and launch flow executions.
 void setInputMapper(org.springframework.binding.mapping.AttributeMapper inputMapper)
          Sets the service responsible for mapping attributes of an ExternalContext to a new FlowExecution during a launch flow operation.
 void setViewIdMapper(ViewIdMapper viewIdMapper)
          Sets the JSF view id mapper used by this phase listener.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected final org.apache.commons.logging.Log logger
Logger, usable by subclasses.

Constructor Detail

FlowPhaseListener

public FlowPhaseListener()
Method Detail

getArgumentHandler

public FlowExecutorArgumentHandler getArgumentHandler()
Returns the argument handler used by this phase listener.


setArgumentHandler

public void setArgumentHandler(FlowExecutorArgumentHandler argumentHandler)
Sets the handler for arguments needed by this phase listener to restore and launch flow executions. This handler is responsible for two things:
  1. Helping in the restoration of the "current" FlowExecution by extracting arguments from the request. Specifically:
    • The flowExecutionKey argument is extracted to perform a flow execution refresh on redirects and browser refreshes.
    • The flowId argument is extracted to perform a flow execution launch on direct browser access of a flow definition URL.
  2. Generating URLs exposing the proper flow execution arguments. Specifically:
    • Generating the flow execution URL to redirect to on a FlowExecutionRedirect response.
    • Generating the flow definition URL to redirect to on a FlowDefinitionRedirect response.
    • Generating external URLs to redirect to on a ExternalRedirect response.

Parameters:
argumentHandler - the argument handler

getInputMapper

public org.springframework.binding.mapping.AttributeMapper getInputMapper()
Returns the configured flow execution input mapper.


setInputMapper

public void setInputMapper(org.springframework.binding.mapping.AttributeMapper inputMapper)
Sets the service responsible for mapping attributes of an ExternalContext to a new FlowExecution during a launch flow operation. The default implementation simply exposes all request parameters as flow execution input attributes. May be null.

Parameters:
inputMapper - the input mapper
See Also:
RequestParameterInputMapper

getViewIdMapper

public ViewIdMapper getViewIdMapper()
Returns the JSF view id resolver used by this phase listener.


setViewIdMapper

public void setViewIdMapper(ViewIdMapper viewIdMapper)
Sets the JSF view id mapper used by this phase listener. The FlowPhaseListener.DefaultViewIdMapper provides a mechanism to convert a logical Spring Web Flow application view name into a JSF view id.
JSF view ids are important to this phase listener: it uses them to check whether the current view has changed, and if a new view needs to be created and activated by delegating to the application's ViewHandler.
A view handler typically treats a JSF view id as the physical location of a view template encapsulating a page layout. The JSF view id normally specifies the physical location of the view template minus a suffix. View handlers typically replace the suffix of any view id with their own default suffix (e.g. ".jsp" or ".xhtml") and then try to locate a physical template view.
The FlowPhaseListener.DefaultViewIdMapper provides the ability to customize how SWF view name is mapped to a JSF view id that will be passed to the ViewHandler. The default value for the view id mapper is a FlowPhaseListener.DefaultViewIdMapper which just returns the SWF viewId as-is.

Parameters:
viewIdMapper - the view id mapper
See Also:
prepareApplicationView(FacesContext, FlowExecutionHolder)

getPhaseId

public javax.faces.event.PhaseId getPhaseId()
Specified by:
getPhaseId in interface javax.faces.event.PhaseListener

beforePhase

public void beforePhase(javax.faces.event.PhaseEvent event)
Specified by:
beforePhase in interface javax.faces.event.PhaseListener

afterPhase

public void afterPhase(javax.faces.event.PhaseEvent event)
Specified by:
afterPhase in interface javax.faces.event.PhaseListener

restoreFlowExecution

protected void restoreFlowExecution(javax.faces.context.FacesContext facesContext)

handleFlowExecutionAccessException

protected void handleFlowExecutionAccessException(FlowExecutionAccessException e,
                                                  javax.faces.context.FacesContext context)
Hook method to handle a thrown flow execution access exception. By default this implementation simply rethrows the exception. Subclasses may override this method to redirect to an error page or take some other action in the case where a flow execution could not be restored (for example, because the flow execution had previously ended or expired).

Parameters:
e - the flow execution access exception
context - the current faces context

createInput

protected MutableAttributeMap createInput(ExternalContext context)
Factory method that creates the input attribute map for a newly created FlowExecution. This implementation uses the registered input mapper, if any.

Parameters:
context - the external context
Returns:
the input map, or null if no input

prepareResponse

protected void prepareResponse(JsfExternalContext context,
                               FlowExecutionHolder holder)
Prepare the appropriate JSF response (e.g. rendering a view, sending a redirect, etc).

Parameters:
context - the context
holder - the holder

prepareApplicationView

protected void prepareApplicationView(javax.faces.context.FacesContext facesContext,
                                      FlowExecutionHolder holder)
Prepare the JSF view for rendering.

Parameters:
facesContext - the faces context
holder - the holder of the current flow execution

createFlowExecutionKeyStateHolder

protected FlowExecutionKeyStateHolder createFlowExecutionKeyStateHolder()
Factory method that creates the state holder UI component that will track the flow execution key used for execution restoration during subsequent restore view phases. Subclasses may override to customize the state holder component implementation, for example--to handle flow execution restoration/access exceptions in a certain way.

Returns:
the flow execution key state holder
See Also:
saveInViewRoot(FacesContext, String)

saveFlowExecution

protected void saveFlowExecution(JsfExternalContext context,
                                 FlowExecutionHolder holder)
Updates the current flow execution in the repository.

Parameters:
context - the external context
holder - the current flow execution holder

sendRedirect

protected void sendRedirect(java.lang.String url,
                            javax.faces.context.FacesContext context)
Helper method to issue a redirect in a JSF environment properly. Subclasses may use as utility code.

Parameters:
url - the url to redirect to
context - the faces context


Copyright © 2009 Spring Framework. All Rights Reserved.