232 lines
9.7 KiB
XML
232 lines
9.7 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="system-setup">
|
|
<title>System Setup</title>
|
|
<sect1 id="system-setup-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This chapter shows you how to setup the Web Flow system for use in any web environment.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="system-config-schema">
|
|
<title>webflow-config.xsd</title>
|
|
<para>
|
|
Web Flow provides a Spring schema that allows you to configure the system.
|
|
To use this schema, include it in one of your infrastructure-layer beans files:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<beans xmlns="http://www.springframework.org/schema/beans"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xmlns:webflow="http://www.springframework.org/schema/webflow-config"
|
|
xsi:schemaLocation="
|
|
http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
|
|
http://www.springframework.org/schema/webflow-config
|
|
http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.0.xsd">
|
|
|
|
<!-- Setup Web Flow here -->
|
|
|
|
</beans>]]>
|
|
</programlisting>
|
|
</sect1>
|
|
<sect1 id="system-config-basic">
|
|
<title>Basic system configuration</title>
|
|
<para>
|
|
The next section shows the minimal configuration required to set up the Web Flow system in your application.
|
|
</para>
|
|
<sect2 id="basic-setup-flow-registry">
|
|
<title>FlowRegistry</title>
|
|
<para>
|
|
Register your flows in a <code>FlowRegistry</code>:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-registry id="flowRegistry">
|
|
<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
|
|
</webflow:flow-registry>]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="basic-setup-flow-executor">
|
|
<title>FlowExecutor</title>
|
|
<para>
|
|
Deploy a FlowExecutor, the central service for executing flows:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry" />]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="flow-registry">
|
|
<title>flow-registry options</title>
|
|
<sect2 id="flow-registry-builder-services">
|
|
<title>Configuring custom FlowBuilder services</title>
|
|
<para>
|
|
Use the <code>flow-builder-services</code> attribute to customize the services used to build the flows in a 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.
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<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" />]]>
|
|
</programlisting>
|
|
<para>
|
|
The configurable services are the <code>conversion-service</code>, <code>formatter-registry</code>, <code>expression-parser</code>, and <code>view-factory-creator</code>.
|
|
These services are configured by referencing custom beans you define. For example:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-builder-services id="flowBuilderServices"
|
|
conversion-service="conversionService"
|
|
formatter-registry="formatterRegistry"
|
|
expression-parser="expressionParser"
|
|
view-factory-creator="viewFactoryCreator" />
|
|
|
|
<bean id="conversionService" class="..." />
|
|
<bean id="formatterRegistry" class="..." />
|
|
<bean id="expressionParser" class="..." />
|
|
<bean id="viewFactoryCreator" class="..." />]]>
|
|
</programlisting>
|
|
<sect3 id="builder-service-conversion">
|
|
<title>conversion-service</title>
|
|
<para>
|
|
Use the <code>conversion-service</code> attribute to customize the <code>ConversionService</code> used by the Web Flow system.
|
|
Converters are used to convert from one type to another when required during flow execution.
|
|
The default ConversionService registers converters for your basic object types such as numbers, classes, and enums.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="builder-service-formatter">
|
|
<title>formatter-registry</title>
|
|
<para>
|
|
Use the <code>formatter-registry</code> attribute to customize the <code>FormatterRegistry</code> used by the Web Flow system.
|
|
Formatters are used by Views to format model property values for display.
|
|
The default FormatterRegistry registers converters for your basic model object types such as numbers and dates.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="builder-service-expression-parser">
|
|
<title>expression-parser</title>
|
|
<para>
|
|
Use the <code>expression-parser</code> attribute to customize the <code>ExpressionParser</code> used by the Web Flow system.
|
|
The default ExpressionParser uses the Unified EL if available on the classpath, otherwise OGNL is used.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="builder-service-view-factory-creator">
|
|
<title>view-factory-creator</title>
|
|
<para>
|
|
Use the <code>view-factory-creator</code> attribute to customize the <code>ViewFactoryCreator</code> used by the Web Flow system.
|
|
The default ViewFactoryCreator produces Spring MVC ViewFactories capable of rendering JSP, Velocity, and Freemarker views.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="flow-registry-parent">
|
|
<title>Configuring FlowRegistry hierarchies</title>
|
|
<para>
|
|
Use the <code>parent</code> 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.
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<!-- 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>]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="flow-registry-location">
|
|
<title>Specifying flow locations</title>
|
|
<para>
|
|
Use the <code>location</code> 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.
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="flow-registry-location-id">
|
|
<title>Assigning custom flow identifiers</title>
|
|
<para>
|
|
Specify an id to assign a custom registry identifier to a flow:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" id="bookHotel" />]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="flow-registry-location-attributes">
|
|
<title>Assigning flow meta-attributes</title>
|
|
<para>
|
|
Use the <code>flow-definition-attributes</code> element to assign custom meta-attributes to a registered flow:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-location path="/WEB-INF/flows/booking/booking.xml">
|
|
<flow-definition-attributes>
|
|
<attribute name="caption" value="Books a hotel" />
|
|
<attribute name="persistence-context" value="true" type="boolean" />
|
|
</flow-definition-attributes>
|
|
</webflow:flow-location>]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="flow-registry-patterns">
|
|
<title>Registering flows using a location pattern</title>
|
|
<para>
|
|
Use the <code>flow-location-patterns</code> element to register flows that match a specific resource location pattern:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<webflow:flow-location-pattern value="/WEB-INF/flows/**/*-flow.xml" />]]>
|
|
</programlisting>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="flow-executor">
|
|
<title>flow-executor options</title>
|
|
<sect2 id="flow-executor-execution-listeners">
|
|
<title>Attaching flow execution listeners</title>
|
|
<para>
|
|
Use the <code>flow-execution-listeners</code> element to register listeners that observe the lifecycle of flow executions:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<flow-execution-listeners>
|
|
<listener ref="securityListener"/>
|
|
<listener ref="persistenceListener"/>
|
|
</flow-execution-listeners>]]>
|
|
</programlisting>
|
|
<para>
|
|
You may also configure a listener to observe only certain flows:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<listener ref="securityListener" criteria="securedFlow1,securedFlow2"/>]]>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="tuning-flow-execution-repository">
|
|
<title>Tuning FlowExecution persistence</title>
|
|
<para>
|
|
Use the <code>flow-execution-repository</code> element to tune flow execution persistence settings:
|
|
</para>
|
|
<programlisting type="xml"><![CDATA[
|
|
<flow-execution-repository max-conversations="5" max-snapshots="30" />]]>
|
|
</programlisting>
|
|
<sect3 id="repository-max-conversations">
|
|
<title>max-conversations</title>
|
|
<para>
|
|
Tune the <code>max-conversations</code> attribute to place a cap on the number of conversations that can be created per user session.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="repository-max-snapshots">
|
|
<title>max-snapshots</title>
|
|
<para>
|
|
Tune the <code>max-snapshots</code> attribute to place a cap on the number of flow execution snapshots that can be taken per conversation.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="repository-conversation-manager">
|
|
<title>conversation-manager</title>
|
|
<para>
|
|
Set a custom <code>ConversationManager</code> to completely customize where conversational flow state is persisted.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter> |