Request vs. Flow Scope: documentation?

[Tom Hicks]

Where can we get a clear definition of Request Scope vs. Flow Scope?

I can't find one in any of the documentation that says how these
relate to each other, how they relate to Servlet scoping, what the
lifetime of variables in each scope is, how to make Actions thread safe, etc, etc.

I think some more documentation would help greatly and
prevent a lot of the questions I'm seeing in this list.

[Colin Yates]

Request scope is for the current request, i.e. the time it takes between the user clicking a button and receiving a response.

Session scope is the time from when the user first connects an independent browser to the server, to the browser shutting down.

Flow scope should be "use case" scope. The start and end of flow scope is defined by the start and end of *your* web flow

HTH.

[Tom Hicks]

Thanks for the quick response.

Your definitions are a good starting point but a little vague.

For instance what does 'clicking a button and
receiving a response' mean? Any HTTP response message?

1) This might explain why my variables disappear at a View,
as follows:

I put a couple of variables into Request scope.
A few actions later they're not there (and my code hasn't explicitly
removed them). However, they were bound (using Spring bind tag)
in a View between the initial action and subsequent actions.

This would be consistent with your definition: they are removed from Request Scope at the View (a response to the user). Correct?


2) OK, what about thread safety? Do I get a new set of Actions
and Views for each Request/Flow (path through the graph)?

Your help greatly appreciated, by the way.

[Keith Donald]

See javadocs of FlowExecution, FlowSession, and RequestContext specifically. (recently updated):

FlowExecution

/**
 * Represents a <i>client instance</i> of an executing top-level flow.
 * <p>
 * This is the central facade interface for managing one runtime execution of a Flow.
 * This is the finite state machine that is the heart of Spring Web Flow.
 * <p>
 * Typically, when a browser wants to launch a new instance of a Flow at runtime, it passes in the
 * id of the Flow definition to launch to a governing <code>FlowExecutionManager</code>.
 * The manager then creates an instance of an object implementing this interface for
 * the requested Flow, which becomes this execution's "root flow".  After creation,
 * the start operation is called, which causes this execution to activate a new session for its
 * root flow definition.  That session is then pushed onto a stack and its definition 
 * becomes the "active flow" for this execution.  A local, internal StateContext object &#40;which extends
 * &#40;&#123;@link org.springframework.webflow.RequestContext&#125;&#41; is then created
 * and the active Flow's start State is entered.
 * <p>
 * In a distributed environment such as HTTP, after the start operation has completed
 * and control returns to the caller &#40;manager&#41;, this execution is typically saved out to some form of
 * storage before the server request ends.  For example it might be saved out to the HttpSession,
 * a Database, or a client-side hidden form field for later restoration and manipulation. 
 * <p>
 * Subsequent requests from the client to manipulate this runtime object, trigger restoration
 * and rehydration of this object, followed by an invocation of the signalEvent operation.
 * The signalEvent operation tells this state machine what action the user took from
 * within the context of the current state&#58; e.g a submit button was pressed, or the cancel button was
 * pressed.  After the event is processed, control again goes back to the client.
 * This continues until an client event causes this flow execution to end, at which time this 
 * object is removed from storage and discarded.
 * 
 * @see org.springframework.webflow.execution.FlowExecutionManager
 * @see org.springframework.webflow.execution.FlowExecutionStorage
 * @see org.springframework.webflow.Flow
 * @see org.springframework.webflow.State
 * @see org.springframework.webflow.FlowSession
 * @see org.springframework.webflow.StateContext
 * 
 * @author Keith Donald
 * @author Erwin Vervaet
 */

FlowSession

/**
 * A runtime object that represents a single client session of a
 * specific <code>Flow</code> definition.  This object maintains all the 
 * state of the session, including its status within exactly one
 * governing FlowExecution and its current State.  This object also acts
 * "flow scope" data model.  Data in "flow scope" lives for the life
 * of this object, and is cleaned up automatically when this object is
 * destroyed.  Destruction happens when this session reaches a end state.
 * <p>
 * This object is fully managed by a FlowExecution within a stack-based 
 * data structure, where each session in the stack is a spawned 
 * flow at a specific state.  The session at the top of the
 * stack is the currently active flow.  This stack of flow sessions captures the
 * complete and current state &#40;snapshot&#41; of an executing flow.
 * <p>
 * A flow session will go through several status changes during its lifecycle.
 * Initially it will be &#123;@link FlowSessionStatus#CREATED&#125;.  For example, when 
 * a new <code>FlowExecution</code> is created to launch a new root 
 * <code>Flow</code> definition a new <code>FlowSession</code> is created.
 * <p>
 * When a flow session is activated &#40;about to be manipulated&#41;, it's status becomes
 * &#123;@link FlowSessionStatus#ACTIVE&#125;.  In the case of a new FlowExecution, 
 * session activation happens immediately after creation to put the "root flow" at
 * the top of the stack and transition it to its start state.
 * <p>
 * When control returns to the client for user think time, the status is updated
 * to &#123;@link FlowSessionStatus#PAUSED&#125;.  The flow is no longer actively 
 * processing&#58; it's stored off somewhere waiting on the user to do something.
 * <p>
 * If a flow session is pushed down in the stack because a subflow is spawned, it's 
 * status becomes &#123;@link FlowSessionStatus#SUSPENDED&#125; until the subflow returns &#40;ends&#41; 
 * and is popped off the stack.  The resuming flow session then becomes active once
 * again.
 * <p>
 * When a flow session is terminated because an EndState is reached, its status
 * becomes &#123;@link FlowSessionStatus#ENDED&#125;, ending its lifecycle.  The session is 
 * popped off the stack and discarded, and any allocated resources in "flow scope" are
 * automatically cleaned up.
 * <p>
 * Note that a flow <i>session</i> is in no way linked to an HTTP session! It
 * just uses the familiar "session" naming convention to denote a stateful 
 * interaction.
 * 
 * @author Keith Donald
 * @author Erwin Vervaet
 */
public interface FlowSession &#123;

RequestContext

/**
 * Central interface that allows clients to access contextual information about
 * an ongoing flow execution within the context of a client request. The term
 * <i>request</i> is used to describe a single call &#40;thread&#41; into the flow system to
 * manipulate exactly one flow execution.
 * <p>
 * A new instance of this object is created when one of the operations on a
 * <code>FlowExecution</code> facade invoked, either
 * &#40;&#123;@link org.springframework.webflow.execution.FlowExecution#start&#40;Event&#41;&#125;
 * to activate a newly created flow execution, or
 * &#123;@link org.springframework.webflow.execution.FlowExecution#signalEvent&#40;Event&#41;&#125;&#41; to
 * signal an event in the current state of an restored flow execution.
 * <p>
 * Once created this context object is passed around throughout request
 * processing where it may be accessed and reasoned upon, typically by
 * user-implemented action code and/or state transition criteria.
 * <p>
 * When a call into a flow execution returns, this object goes out of scope
 * and is disposed of automatically.  Thus, this object is an internal artifact
 * used within a FlowExecution&#58; this object is NOT directly exposed to to external
 * client code.
 * <p>
 * Note&#58; the "requestScope" property may be used as a store for arbitrary data that 
 * should exist for the life of this object.  Such request-local data, along with
 * all data in flow scope, is available for exposing to view templates via a 
 * ViewDescriptor, returned when a ViewState or EndState is entered.
 * See &#40;&#123;@link org.springframework.webflow.ViewState&#125;&#41; for an example using 
 * a specific &#40;&#123;@link org.springframework.webflow.ViewDescriptorCreator&#125;&#41; strategy. 
 * <p>
 * Note&#58; the <i>request</i> context is in no way linked to an HTTP or Portlet request!
 * It uses the familiar "request" naming convention to indicate a single call to
 * manipulate an runtime execution of a flow.
 * 
 * @see org.springframework.webflow.execution.FlowExecution
 * @see org.springframework.webflow.Action
 * @see org.springframework.webflow.TransitionCriteria
 * 
 * @author Keith Donald
 * @author Erwin Vervaet
 */

[klr8]

1) That's exactly what's happening.

2) Basically actions should be stateless and are thus inherintly thread-safe. We just added a StatefulActionProxy in CVS that allows for stateful actions in flow scope (http://cvs.sourceforge.net/viewcvs.p...=1.6&view=auto)

For more info on flow scope versus request scope, check the JavaDoc: http://static.springframework.org/sp.../docs/pr5/api/, especially for the Action class.

Erwin

[Tom Hicks]

Thanks guys!

I had not seen the updated documents and I think I'm on the right track now.
regards,
-tom