10. System Setup

Register your flows in a FlowRegistry in XML:

<webflow:flow-registry id="flowRegistry">
    <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
</webflow:flow-registry>
			

Register your flows in a FlowRegistry in Java:

@Bean
public FlowDefinitionRegistry flowRegistry() {
    return getFlowDefinitionRegistryBuilder()
        .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
        .build();
}
			

Deploy a FlowExecutor, the central service for executing flows in XML:

<webflow:flow-executor id="flowExecutor" />
			

Deploy a FlowExecutor, the central service for executing flows in Java:

@Bean
public FlowExecutor flowExecutor() {
    return getFlowExecutorBuilder(flowRegistry()).build();
}
			

See the Spring MVC and Spring Faces sections of this guide on how to integrate the Web Flow system with the MVC and JSF environment, respectively.

Use the location element to specify paths to flow definitions to register. By default, flows will be assigned registry identifiers equal to their filenames minus the file extension, unless a registry bath path is defined.

In XML:

<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
			

In Java:

return getFlowDefinitionRegistryBuilder()
        .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
        .build();
			

Specify an id to assign a custom registry identifier to a flow in XML:

<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" id="bookHotel" />
			

Specify an id to assign a custom registry identifier to a flow in Java:

return getFlowDefinitionRegistryBuilder()
        .addFlowLocation("/WEB-INF/flows/booking/booking.xml", "bookHotel")
        .build();
			

Use the flow-definition-attributes element to assign custom meta-attributes to a registered flow.

In XML:

<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml">
    <webflow:flow-definition-attributes>
        <webflow:attribute name="caption" value="Books a hotel" />
    </webflow:flow-definition-attributes>
</webflow:flow-location>
			

In Java:

Map<String, Object> attrs = ... ;

return getFlowDefinitionRegistryBuilder()
        .addFlowLocation("/WEB-INF/flows/booking/booking.xml", null, attrs)
        .build();
			

Use the flow-location-patterns element to register flows that match a specific resource location pattern:

In XML:

<webflow:flow-location-pattern value="/WEB-INF/flows/**/*-flow.xml" />
			

In Java:

return getFlowDefinitionRegistryBuilder()
        .addFlowLocationPattern("/WEB-INF/flows/**/*-flow.xml")
        .build();
			

Use the base-path attribute to define a base location for all flows in the application. All flow locations are then relative to the base path. The base path can be a resource path such as '/WEB-INF' or a location on the classpath like 'classpath:org/springframework/webflow/samples'.

In XML:

<webflow:flow-registry id="flowRegistry" base-path="/WEB-INF">
    <webflow:flow-location path="/hotels/booking/booking.xml" />
</webflow:flow-registry>
			

In Java:

return getFlowDefinitionRegistryBuilder()
        .setBasePath("/WEB-INF")
        .addFlowLocationPattern("/hotels/booking/booking.xml")
        .build();
			

With a base path defined, the algorithm that assigns flow identifiers changes slightly. Flows will now be assigned registry identifiers equal to the the path segment between their base path and file name. For example, if a flow definition is located at '/WEB-INF/hotels/booking/booking-flow.xml' and the base path is '/WEB-INF' the remaining path to this flow is 'hotels/booking' which becomes the flow id.

If no base path is not specified or if the flow definition is directly on the base path, flow id assignment from the filename (minus the extension) is used. For example, if a flow definition file is 'booking.xml', the flow identifier is simply 'booking'.

Location patterns are particularly powerful when combined with a registry base path. Instead of the flow identifiers becoming '*-flow', they will be based on the directory path. For example in XML:

<webflow:flow-registry id="flowRegistry" base-path="/WEB-INF">
    <webflow:flow-location-pattern value="/**/*-flow.xml" />
</webflow:flow-registry>
			

In Java:

return getFlowDefinitionRegistryBuilder()
        .setBasePath("/WEB-INF")
        .addFlowLocationPattern("/**/*-flow.xml")
        .build();
			

In the above example, suppose you had flows located in /user/login, /user/registration, /hotels/booking, and /flights/booking directories within WEB-INF, you'd end up with flow ids of user/login, user/registration, hotels/booking, and flights/booking, respectively.

Use the parent attribute to link two flow registries together in a hierarchy. When the child registry is queried, if it cannot find the requested flow it will delegate to its parent.

In XML:

<!-- my-system-config.xml -->
<webflow:flow-registry id="flowRegistry" parent="sharedFlowRegistry">
    <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
</webflow:flow-registry>

<!-- shared-config.xml -->
<webflow:flow-registry id="sharedFlowRegistry">
    <!-- Global flows shared by several applications -->
</webflow:flow-registry>
			

In Java:

@Configuration
public class WebFlowConfig extends AbstractFlowConfiguration {

    @Autowired
    private SharedConfig sharedConfig;

    @Bean
    public FlowDefinitionRegistry flowRegistry() {
        return getFlowDefinitionRegistryBuilder()
                .setParent(this.sharedConfig.sharedFlowRegistry())
                .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
                .build();
    }
}

@Configuration
public class SharedConfig extends AbstractFlowConfiguration {

    @Bean
    public FlowDefinitionRegistry sharedFlowRegistry() {
        return getFlowDefinitionRegistryBuilder()
                .addFlowLocation("/WEB-INF/flows/shared.xml")
                .build();
    }
}
			

Use the flow-builder-services attribute to customize the services and settings used to build flows in a flow-registry. If no flow-builder-services tag is specified, the default service implementations are used. When the tag is defined, you only need to reference the services you want to customize.

In XML:

<webflow:flow-registry id="flowRegistry" flow-builder-services="flowBuilderServices">
    <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
</webflow:flow-registry>

<webflow:flow-builder-services id="flowBuilderServices" />
			

In Java:

@Bean
public FlowDefinitionRegistry flowRegistry() {
	return getFlowDefinitionRegistryBuilder(flowBuilderServices())
            .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
            .build();
}

@Bean
public FlowBuilderServices flowBuilderServices() {
    return getFlowBuilderServicesBuilder().build();
}
			

The configurable services are the conversion-service, expression-parser, and view-factory-creator. These services are configured by referencing custom beans you define.

For example in XML:

<webflow:flow-builder-services id="flowBuilderServices"
    conversion-service="conversionService"
    expression-parser="expressionParser"
    view-factory-creator="viewFactoryCreator" />

<bean id="conversionService" class="..." />
<bean id="expressionParser" class="..." />
<bean id="viewFactoryCreator" class="..." />
			

In Java:

@Bean
public FlowBuilderServices flowBuilderServices() {
    return getFlowBuilderServicesBuilder()
            .setConversionService(conversionService())
            .setExpressionParser(expressionParser)
            .setViewFactoryCreator(mvcViewFactoryCreator())
            .build();
}

@Bean
public ConversionService conversionService() {
    // ...
}

@Bean
public ExpressionParser expressionParser() {
    // ...
}

@Bean
public ViewFactoryCreator viewFactoryCreator() {
    // ...
}
			

Use the flow-execution-listeners element to register listeners that observe the lifecycle of flow executions. For example in XML:

<webflow:flow-execution-listeners>
    <webflow:listener ref="securityListener"/>
    <webflow:listener ref="persistenceListener"/>
</webflow:flow-execution-listeners>
			

In Java:

@Bean
public FlowExecutor flowExecutor() {
    return getFlowExecutorBuilder(flowRegistry())
            .addFlowExecutionListener(securityListener())
            .addFlowExecutionListener(persistenceListener())
            .build();
}
			

You may also configure a listener to observe only certain flows. For example in XML:

<webflow:listener ref="securityListener" criteria="securedFlow1,securedFlow2"/>
			

In Java:

@Bean
public FlowExecutor flowExecutor() {
    return getFlowExecutorBuilder(flowRegistry())
            .addFlowExecutionListener(securityListener(), "securedFlow1,securedFlow2")
            .build();
}
			

Use the flow-execution-repository element to tune flow execution persistence settings. For example in XML:

<webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry">
    <webflow:flow-execution-repository max-executions="5" max-execution-snapshots="30" />
</webflow:flow-executor>
			

In Java:

@Bean
public FlowExecutor flowExecutor() {
    return getFlowExecutorBuilder(flowRegistry())
            .setMaxFlowExecutions(5)
            .setMaxFlowExecutionSnapshots(30)
            .build();
}