# Flow executors

## Introduction

Flow executors are the highest-level entry points into the Spring Web Flow system, responsible for driving the execution of flows across a variety of environments.

In this chapter, you will learn how to execute flows within Spring MVC, Struts, and Java Server Faces (JSF) based applications.

## FlowExecutor

`org.springframework.webflow.executor.FlowExecutor` is the central facade interface external systems use to drive the execution of flows. This facade acts as a simple, convenient service entry-point into the Spring Web Flow system that is reusable across environments.

The `FlowExecutor` interface is shown below:

        public interface FlowExecutor {
            public void executeFlowRequest(ExternalContext context);
        }

Execution typically consists of either:

1. Launching (start) a new execution of a flow definition.

2. Resuming a paused flow execution by signaling an event against its current state.

The ExternalContext provides normalized access to properties of an external system that has called into Spring Web Flow. This context allows access to environment-specific request parameters as well as externally-managed request, session, and application-level attributes.

`ExternalContext` implementations exist for each of the environments Spring Web Flow supports. If a flow artifact such as an Action needs to access native constructs of the calling environment it can downcast a context to its specific implementation. The need for such downcasting is considered a corner case.

### FlowExecutorImpl

The default executor implementation is `org.springframework.webflow.executor.FlowExecutorImpl`. It allows for configuration of a `FlowDefinitionLocator` responsible for loading the flow definitions to execute, as well as the `FlowExecutionRepository` strategy responsible for persisting flow executions that remain active beyond a single request into the server.

The configurable `FlowExecutorImpl` properties are shown below:

#### FlowExecutorImpl properties

Property name | Description | Cardinality
--- | --- | ---
definitionLocator | The service for loading flow definitions to be executed, typically a `FlowDefinitionRegistry` | 1
executionFactory | The factory for creating new flow executions. | 1
executionRepository | The repository for saving and loading persistent (paused) flow executions | 1

### A typical flow executor configuration with Spring 2.0

        <?xml version="1.0" encoding="UTF-8"?>
        <beans xmlns="http://www.springframework.org/schema/beans"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:web="http://www.springframework.org/schema/webflow-config"
               xsi:schemaLocation="
                   http://www.springframework.org/schema/beans
                   http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                   http://www.springframework.org/schema/webflow-config
                   http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.0.xsd">

            <!-- Launches new flow executions and resumes existing executions. -->
            <web:flow-executor id="flowExecutor" registry-ref="flowRegistry"/>

            <!-- Creates the registry of flow definitions for this application -->
            <web:flow-registry id="flowRegistry">
                <web:flow-location path="/WEB-INF/flows/**/*-flow.xml"/>
            </web:flow-registry>

        </beans>

This instructs Spring to create a flow executor that can execute all XML-based flow definitions contained within the `/WEB-INF/flows` directory. The default flow execution repository, `continuation`, is used.

### A flow executor using a simple execution repository

        <web:flow-executor id="flowExecutor" registry-ref="flowRegistry" repository-type="simple"/>

This executor is configured with a simple repository that manages execution state in the user session.

### A flow executor using a client-side continuation-based execution repository

        <web:flow-executor id="flowExecutor" registry-ref="flowRegistry" repository-type="client"/>

This executor is configured with a continuation-based repository that serializes continuation state to the client using no server-side state.

### A flow executor using a single key execution repository

        <web:flow-executor id="flowExecutor" registry-ref="flowRegistry" repository-type="singleKey"/>>

This executor is configured with a simple repository that assigns a single flow execution key per conversation. The key, once assigned, never changes for the duration of the conversation.

### A flow executor setting custom conversation management attributes

        <web:flow-executor id="flowExecutor" registry-ref="flowRegistry">
            <web:flow-repository type="continuation" max-conversations="5" max-continuations="30" conversation-manager-ref="conversationManager"/>
        </web:flow-executor>

        <bean id="conversationManager" class="example.MyCustomConversationalStateManager"/>

This executor is configured with a continuation repository configured with custom settings for:

1. The maximum number of active conversations per user session (5)

2. The maximum number of restorable flow execution snapshots (continuations) per conversation (30)

3. Where conversational state will be stored (via a custom conversationManager)

The `flow:repository` child element is the more flexible form for configuring the flow execution repository. Use it or the convenient `repository-type` attribute, not both.

### A flow executor setting system execution attributes

        <web:flow-executor id="flowExecutor" registry-ref="flowRegistry" repository-type="continuation">
            <web:flow-execution-attributes>
                <web:alwaysRedirectOnPause value="false"/>
                <web:attribute name="foo" value="bar"/>
            </flow:execution-attributes>
        </web:flow-executor>

This executor is configured to set two flow execution system attributes `alwaysRedirectOnPause=false` and `foo=bar`.

The `alwaysRedirectOnPause` attribute determines if a flow execution redirect occurs automatically each time an execution pauses (automated `POST+REDIRECT+GET` behavior). Setting this attribute to false will disable the default 'true' behavior.

### A flow executor setting custom execution listeners

        <web:flow-executor id="flowExecutor" registry-ref="flowRegistry" repository-type="continuation">
            <web:flow-execution-listeners>
                <web:flow-listener ref="listener" criteria="order-flow"/>
            </web:flow-execution-listeners>
        </web:flow-executor>

        <!-- A FlowExecutionListener to observe the lifecycle of order-flow executions -->
        <bean id="listener" class="example.OrderFlowExecutionListener"/>

This executor is configured to apply the execution listener to the "order-flow".