org.springframework.webflow.execution
Interface Action

All Known Implementing Classes:

AbstractAction, AnnotatedAction, CompositeAction, EvaluateAction, ExternalRedirectAction, FlowDefinitionRedirectAction, FormAction, MockAction, MultiAction, RenderAction, SetAction, ViewFactoryActionAdapter

public interface Action

A command that executes a behavior and returns a logical execution result a calling flow execution can respond to.

Actions typically delegate down to the application (or service) layer to perform business operations. They often retrieve data to support response rendering. They act as a bridge between a SWF web-tier and your middle-tier business logic layer.

When an action completes execution it signals a result event describing the outcome of that execution (for example, "success", "error", "yes", "no", "tryAgain", etc). In addition to providing a logical outcome the flow can respond to, a result event may have payload associated with it, for example a "success" return value or an "error" error code. The result event is typically used as grounds for a state transition out of the current state of the calling Flow.

Action implementations are often application-scoped singletons instantiated and managed by a web-tier Spring application context to take advantage of Spring's externalized configuration and dependency injection capabilities (which is a form of Inversion of Control [IoC]). Actions may also be stateful prototypes, storing conversational state as instance variables. Action instance definitions may also be locally scoped to a specific flow definition (see use of the "import" element of the root XML flow definition element.)

Note: Actions are directly instantiatable for use in a standalone test environment and can be parameterized with mocks or stubs, as they are simple POJOs. Action proxies may also be generated at runtime for delegating to POJO business operations that have no dependency on the Spring Web Flow API.

Note: if an Action is a singleton managed in application scope, take care not to store and/or modify caller-specific state in a unsafe manner. The Action execute(RequestContext) method runs in an independently executing thread on each invocation so make sure you deal only with local data or internal, thread-safe services.

Note: an Action is not a controller like a Spring MVC controller or a Struts action is a controller. Flow actions are commands. Such commands do not select views, they execute arbitrary behavioral logic and then return an logical execution result. The flow that invokes an Action is responsible for responding to the execution result to decide what to do next. In Spring Web Flow, the flow is the controller.

Author:

Keith Donald, Erwin Vervaet

Method Summary

Event

execute(RequestContext context) Execute this action.

Method Detail

execute

Event execute(RequestContext context)
              throws java.lang.Exception

Execute this action. Action execution will occur in the context of a request associated with an active flow execution.

Action invocation is typically triggered in a production environment by a state within a flow carrying out the execution of a flow definition. The result of action execution, a logical outcome event, can be used as grounds for a transition out of the calling state.

Note: The RequestContext argument to this method provides access to data about the active flow execution in the context of the currently executing thread. Among other things, this allows this action to access data set by other actions, as well as set its own attributes it wishes to expose in a given scope.

Some notes about actions and their usage of the attribute scope types:

• Attributes set in request scope exist for the life of the currently executing request only.
• Attributes set in flash scope exist until the next external user event is signaled. That time includes the current request plus any redirect or additional refreshes to the next view.
• Attributes set in flow scope exist for the life of the flow session and will be cleaned up automatically when the flow session ends.
• Attributes set in conversation scope exist for the life of the entire flow execution representing a single logical "conversation" with a user.

All attributes present in any scope are typically exposed in a model for access by a view when an "interactive" state type such as a view state is entered.

Note: flow scope should generally not be used as a general purpose cache, but rather as a context for data needed locally by other states of the flow this action participates in. For example, it would be inappropriate to stuff large collections of objects (like those returned to support a search results view) into flow scope. Instead, put such result collections in request scope, and ensure you execute this action again each time you wish to view those results. 2nd level caches managed outside of SWF are more general cache solutions.

Note: as flow scoped attributes are eligible for serialization they should be Serializable.

Parameters:

context - the action execution context, for accessing and setting data in a scope type, as well as obtaining other flow contextual information (e.g. request context attributes and flow execution context information)

Returns:

a logical result outcome, used as grounds for a transition in the calling flow (e.g. "success", "error", "yes", "no", * ...)

Throws:

java.lang.Exception - a exception occurred during action execution, either checked or unchecked; note, any recoverable exceptions should be caught within this method and an appropriate result outcome returned or be handled by the current state of the calling flow execution.