org.springframework.webflow.execution
Interface RequestContext

All Known Subinterfaces:

RequestControlContext

All Known Implementing Classes:

MockRequestContext, MockRequestControlContext

public interface RequestContext

A context for a single request to manipulate a flow execution. Allows Web Flow users to access contextual information about the executing request, as well as the governing active flow execution.

The term request is used to describe a single call (thread) into the flow system by an external actor to manipulate exactly one flow execution.

A new instance of this object is typically created when one of the core operations supported by a flow execution is invoked, either start to launch the flow execution, signalEvent to resume the flow execution, or refresh to reconstitute the flow execution's last view selection for purposes of reissuing a user response.

Once created this context object is passed around throughout flow execution request processing where it may be accessed and reasoned upon by SWF-internal artifacts such as states, user-implemented action code, and state transition criteria.

When a call into a flow execution returns this object goes out of scope and is disposed of automatically. Thus a request context is an internal artifact used within a FlowExecution: this object is not exposed to external client code, e.g. a view implementation (JSP).

The requestScope property may be used as a store for arbitrary data that should exist for the life of this object. Request-scoped data, along with all data in flash scope, flow scope and conversation scope is available for exposing to view templates via a model property.

The web flow system will ensure that a RequestContext object is local to the current thread. It can be safely manipulated without needing to worry about concurrent access.

Note: this request 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 a runtime execution of a flow definition.

Author:

Keith Donald, Erwin Vervaet

Method Summary

FlowDefinition	getActiveFlow() Returns the definition of the flow that is currently executing.
AttributeMap	getAttributes() Returns a context map for accessing arbitrary attributes about the state of the current request.
MutableAttributeMap	getConversationScope() Returns a mutable accessor for accessing and/or setting attributes in conversation scope.
StateDefinition	getCurrentState() Returns the current state of the executing flow.
ExternalContext	getExternalContext() Returns the external client context that originated (or triggered) this request.
MutableAttributeMap	getFlashScope() Returns a mutable accessor for accessing and/or setting attributes in flash scope.
FlowExecutionContext	getFlowExecutionContext() Returns contextual information about the flow execution itself.
MutableAttributeMap	getFlowScope() Returns a mutable accessor for accessing and/or setting attributes in flow scope.
Event	getLastEvent() Returns the last event signaled during this request.
TransitionDefinition	getLastTransition() Returns the last state transition that executed in this request.
AttributeMap	getModel() Returns the data model capturing the state of this context, suitable for exposing to clients (mostly web views).
ParameterMap	getRequestParameters() Returns the immutable input parameters associated with this request into Spring Web Flow.
MutableAttributeMap	getRequestScope() Returns a mutable accessor for accessing and/or setting attributes in request scope.
void	setAttributes(AttributeMap attributes) Set the contextual attributes describing the state of this request.

Method Detail

getActiveFlow

FlowDefinition getActiveFlow()
                             throws java.lang.IllegalStateException

Returns the definition of the flow that is currently executing.

Returns:

the flow definition for the active session

Throws:

java.lang.IllegalStateException - if the flow execution has not been started at all, or if the execution has ended and is no longer actively executing

getCurrentState

StateDefinition getCurrentState()
                                throws java.lang.IllegalStateException

Returns the current state of the executing flow. May return null if this flow execution is in the process of starting and has not yet entered its start state.

Returns:

the current state, or null if in the process of starting

Throws:

java.lang.IllegalStateException - if this flow execution has not been started at all, or if this execution has ended and is no longer actively executing

getRequestScope

MutableAttributeMap getRequestScope()

Returns a mutable accessor for accessing and/or setting attributes in request scope. Request scoped attributes exist for the duration of this request only.

Returns:

the request scope

getFlashScope

MutableAttributeMap getFlashScope()

Returns a mutable accessor for accessing and/or setting attributes in flash scope. Flash scoped attributes exist untill the next event is signaled in the flow execution.

Returns:

the flash scope

getFlowScope

MutableAttributeMap getFlowScope()

Returns a mutable accessor for accessing and/or setting attributes in flow scope. Flow scoped attributes exist for the life of the active flow session.

Returns:

the flow scope

See Also:

FlowSession

getConversationScope

MutableAttributeMap getConversationScope()

Returns a mutable accessor for accessing and/or setting attributes in conversation scope. Conversation scoped attributes exist for the life of the executing flow and are shared across all flow sessions.

Returns:

the conversation scope

See Also:

FlowExecutionContext

getRequestParameters

ParameterMap getRequestParameters()

Returns the immutable input parameters associated with this request into Spring Web Flow. The map returned is immutable and cannot be changed.

This is typically a convenient shortcut for accessing the ExternalContext.getRequestParameterMap() directly.

See Also:

getExternalContext()

getExternalContext

ExternalContext getExternalContext()

Returns the external client context that originated (or triggered) this request.

Acting as a facade, the returned context object provides a single point of access to the calling client's environment. It provides normalized access to attributes of the client environment without tying you to specific constructs within that environment.

In addition, this context may be downcastable to a specific context type for a specific client environment, such as a ServletExternalContext for servlets or a PortletExternalContext for portlets. Such downcasting will give you full access to a native HttpServletRequest, for example. With that said, for portability reasons you should avoid coupling your flow artifacts to a specific deployment environment when possible.

Returns:

the originating external context, the one that triggered the current execution request

getFlowExecutionContext

FlowExecutionContext getFlowExecutionContext()

Returns contextual information about the flow execution itself. Information in this context typically spans more than one request.

Returns:

the flow execution context

getLastEvent

Event getLastEvent()

Returns the last event signaled during this request. The event may or may not have caused a state transition to happen.

Returns:

the last signaled event, or null if no event has been signaled yet

getLastTransition

TransitionDefinition getLastTransition()

Returns the last state transition that executed in this request.

Returns:

the last transition, or null if no transition has occured yet

getAttributes

AttributeMap getAttributes()

Returns a context map for accessing arbitrary attributes about the state of the current request. These attributes may be used to influence flow execution behavior.

Returns:

the current attributes of this request, or empty if not set

setAttributes

void setAttributes(AttributeMap attributes)

Set the contextual attributes describing the state of this request. Overwrites any pre-existing collection.

Parameters:

attributes - the attributes

getModel

AttributeMap getModel()

Returns the data model capturing the state of this context, suitable for exposing to clients (mostly web views). Typically the model will contain the union of the data available in request, flash, session and conversation scope.

Returns:

the model that can be exposed to a client view for rendering purposes