Spring/spring-webflow
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

remaining sections of docs

Browse Source 
portlet, mvc, and persistence still need to be completed.
faces need more detail and a component reference.
This commit is contained in:
Keith Donald
2008-04-10 04:51:17 +00:00
parent 358f30598e
commit c97d2264a8
8 changed files with 289 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
spring-webflow-reference/src/flow-managed-persistence.xml Normal file
View File

@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="flow-managed-persistence">
<title>Flow Managed Persistence</title>
<sect1 id="spring-mvc-introduction">
<title>Introduction</title>
<para>
This chapter shows you how to use flows to manage web application persistence.
</para>
</sect1>
</chapter>

65
spring-webflow-reference/src/flow-security.xml
View File

@@ -76,14 +76,12 @@
</para>
<programlisting language="xml">
&lt;webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry"&gt;
&lt;webflow:flow-execution-listeners&gt;
&lt;webflow:listener ref="securityFlowExecutionListener" /&gt;
...
&lt;/webflow:flow-execution-listeners&gt;
&lt;webflow:flow-execution-listeners&gt;
&lt;webflow:listener ref="securityFlowExecutionListener" /&gt;
&lt;/webflow:flow-execution-listeners&gt;
&lt;/webflow:flow-executor&gt;
&lt;bean id="securityFlowExecutionListener"
class="org.springframework.webflow.security.SecurityFlowExecutionListener" /&gt;
&lt;bean id="securityFlowExecutionListener" class="org.springframework.webflow.security.SecurityFlowExecutionListener" /&gt;
</programlisting>
<para>
If your application is using authorities that are not role based, you will need to configure a custom <code>AccessDecisionManager</code>.
@@ -91,9 +89,8 @@
Please consult the Spring Security documentation to learn more about decision managers.
</para>
<programlisting language="xml">
&lt;bean id="securityFlowExecutionListener"
class="org.springframework.webflow.security.SecurityFlowExecutionListener"&gt;
&lt;property name="accessDecisionManager" ref="myCustomAccessDecisionManager" /&gt;
&lt;bean id="securityFlowExecutionListener" class="org.springframework.webflow.security.SecurityFlowExecutionListener"&gt;
&lt;property name="accessDecisionManager" ref="myCustomAccessDecisionManager" /&gt;
&lt;/bean&gt;
</programlisting>
<para>
@@ -120,42 +117,26 @@
</para>
<programlisting language="xml">
&lt;security:http auto-config="true"&gt;
&lt;!-- restrict URLs based on role --&gt;
&lt;security:intercept-url pattern="/spring/login*" access="ROLE_ANONYMOUS" /&gt;
&lt;security:intercept-url pattern="/spring/logout-success*" access="ROLE_ANONYMOUS" /&gt;
&lt;security:intercept-url pattern="/spring/logout*" access="ROLE_USER" /&gt;
&lt;!-- override default login and logout pages --&gt;
&lt;security:form-login login-page="/spring/login"
login-url="/spring/login-process"
default-target-url="/spring/main"
authentication-failure-url="/spring/login?login_error=1" /&gt;
&lt;security:logout logout-url="/spring/logout"
logout-success-url="/spring/logout-success" /&gt;
&lt;security:intercept-url pattern="/spring/login*" access="ROLE_ANONYMOUS" /&gt;
&lt;security:intercept-url pattern="/spring/logout-success*" access="ROLE_ANONYMOUS" /&gt;
&lt;security:intercept-url pattern="/spring/logout*" access="ROLE_USER" /&gt;
&lt;security:form-login login-page="/spring/login"
login-url="/spring/login-process"
default-target-url="/spring/main"
authentication-failure-url="/spring/login?login_error=1" /&gt;
&lt;security:logout logout-url="/spring/logout" logout-success-url="/spring/logout-success" /&gt;
&lt;/security:http&gt;
&lt;!--
Define local authentication provider, a real app would use an
external provider (JDBC, LDAP, CAS, etc)
usernames/passwords are:
keith/melbourne
erwin/leuven
jeremy/atlanta
scott/rochester
--&gt;
&lt;security:authentication-provider&gt;
&lt;security:password-encoder hash="md5" /&gt;
&lt;security:user-service&gt;
&lt;security:user name="keith" password="417c7382b16c395bc25b5da1398cf076"
authorities="ROLE_USER, ROLE_SUPERVISOR" /&gt;
&lt;security:user name="erwin" password="12430911a8af075c6f41c6976af22b09"
authorities="ROLE_USER, ROLE_SUPERVISOR" /&gt;
&lt;security:user name="jeremy" password="57c6cbff0d421449be820763f03139eb"
authorities="ROLE_USER" /&gt;
&lt;security:user name="scott" password="942f2339bf50796de535a384f0d1af3e"
authorities="ROLE_USER" /&gt;
&lt;/security:user-service&gt;
&lt;security:password-encoder hash="md5" /&gt;
&lt;security:user-service&gt;
&lt;security:user name="keith" password="417c7382b16c395bc25b5da1398cf076" authorities="ROLE_USER,ROLE_SUPERVISOR" /&gt;
&lt;security:user name="erwin" password="12430911a8af075c6f41c6976af22b09" authorities="ROLE_USER,ROLE_SUPERVISOR" /&gt;
&lt;security:user name="jeremy" password="57c6cbff0d421449be820763f03139eb" authorities="ROLE_USER" /&gt;
&lt;security:user name="scott" password="942f2339bf50796de535a384f0d1af3e" authorities="ROLE_USER" /&gt;
&lt;/security:user-service&gt;
&lt;/security:authentication-provider&gt;
</programlisting>
</sect2>

10
spring-webflow-reference/src/portlet.xml Normal file
View File

@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="portlet">
<title>Portlet Integration</title>
<sect1 id="portlet-introduction">
<title>Introduction</title>
<para>
This chapter shows you how to use Web Flow in a Portlet environment.
</para>
</sect1>
</chapter>

5
spring-webflow-reference/src/spring-faces.xml
View File

@@ -1,7 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="spring-faces">
<title>Using Spring Faces</title>
<title>JSF Integration</title>
<sect1 id="spring-faces-introduction">
<title>Introduction</title>
<para>
@@ -114,7 +113,7 @@
managed beans are typically allocated.
</para>
</sect2>
<sect2>
<sect2 id="faces-manipulating-model">
<title>Manipulating The Model</title>
<para>
The need to initialize the model before view rendering (such as by loading persistent entities from a

10
spring-webflow-reference/src/spring-mvc.xml Normal file
View File

@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="spring-mvc">
<title>Spring MVC Integration</title>
<sect1 id="spring-mvc-introduction">
<title>Introduction</title>
<para>
This chapter shows you how to integrate Web Flow into a Spring MVC web application.
</para>
</sect1>
</chapter>

8
spring-webflow-reference/src/spring-webflow-reference.xml
View File

@@ -6,9 +6,13 @@
<!ENTITY defining-flows SYSTEM "defining-flows.xml">
<!ENTITY el SYSTEM "el.xml">
<!ENTITY views SYSTEM "views.xml">
<!ENTITY flow-managed-persistence SYSTEM "flow-managed-persistence.xml">
<!ENTITY flow-security SYSTEM "flow-security.xml">
<!ENTITY flow-inheritance SYSTEM "flow-inheritance.xml">
<!ENTITY system-setup SYSTEM "system-setup.xml">
<!ENTITY spring-mvc SYSTEM "spring-mvc.xml">
<!ENTITY spring-faces SYSTEM "spring-faces.xml">
<!ENTITY portlet SYSTEM "portlet.xml">
<!ENTITY upgrade-guide SYSTEM "upgrade-guide.xml">
<!ENTITY flow-definition-field-mappings SYSTEM "flow-definition-field-mappings.xml">
]>
@@ -73,9 +77,13 @@
&defining-flows;
&el;
&views;
&flow-managed-persistence;
&flow-security;
&flow-inheritance;
&system-setup;
&spring-mvc;
&spring-faces;
&portlet;
&upgrade-guide;
&flow-definition-field-mappings;

213
spring-webflow-reference/src/system-setup.xml
View File

@@ -7,4 +7,217 @@
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">
&lt;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"&gt;
&lt;!-- Setup Web Flow here --&gt;
&lt;/beans&gt;
</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">
&lt;webflow:flow-registry id="flowRegistry"&gt;
&lt;webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" /&gt;
&lt;/webflow:flow-registry&gt;
</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">
&lt;webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry" /&gt;
</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">
&lt;webflow:flow-registry id="flowRegistry" flow-builder-services="flowBuilderServices"&gt;
&lt;webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" /&gt;
&lt;/webflow:flow-registry&gt;
&lt;webflow:flow-builder-services id="flowBuilderServices" /&gt;
</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">
&lt;webflow:flow-builder-services id="flowBuilderServices"
conversion-service="conversionService"
formatter-registry="formatterRegistry"
expression-parser="expressionParser"
view-factory-creator="viewFactoryCreator"/&gt;
&lt;bean id="conversionService" class="..." /&gt;
&lt;bean id="formatterRegistry" class="..." /&gt;
&lt;bean id="expressionParser" class="..." /&gt;
&lt;bean id="viewFactoryCreator" class="..." /&gt;
</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">
&lt;!-- my-system-config.xml --&gt;
&lt;webflow:flow-registry id="flowRegistry" parent="sharedFlowRegistry"&gt;
&lt;webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" /&gt;
&lt;/webflow:flow-registry&gt;
&lt;!-- shared-config.xml --&gt;
&lt;webflow:flow-registry id="sharedFlowRegistry"&gt;
&lt;-- Global flows shared by several applications --&lt;
&lt;/webflow:flow-registry&gt;
</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">
&lt;webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" /&gt;
</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">
&lt;webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" id="bookHotel" /&gt;
</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">
&lt;webflow:flow-location path="/WEB-INF/flows/booking/booking.xml"&gt;
&lt;flow-definition-attributes&gt;
&lt;attribute name="caption" value="Books a hotel" /&gt;
&lt;attribute name="persistence-context" value="true" type="boolean" /&gt;
&lt;/flow-definition-attributes&gt;
&lt;/webflow:flow-location&gt;
</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">
&lt;flow-execution-listeners&gt;
&lt;listener ref="securityListener"/&gt;
&lt;listener ref="persistenceListener"/&gt;
&lt;/flow-execution-listeners&gt;
</programlisting>
<para>
You may also configure a listener to observe only certain flows:
</para>
<programlisting type="xml">
&lt;listener ref="securityListener" criteria="securedFlow1,securedFlow2"/&gt;
</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">
&lt;flow-execution-repository max-conversations="5" max-snapshots="30" /&gt;
</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>

26
spring-webflow-reference/src/views.xml
View File

@@ -8,7 +8,7 @@
</para>
</sect1>
<sect1 id="view-convention">
<title>view-state</title>
<title>Defining view states</title>
<para>
Use the <code>view-state</code> element to define a step of the flow that renders a view and waits for a user event to resume:
</para>
@@ -38,7 +38,7 @@
</mediaobject>
</sect1>
<sect1 id="view-explicit">
<title>Explicit view ids</title>
<title>Specifying view identifiers</title>
<para>
Use the <code>view</code> attribute to explictly specify the id of the view to render.
</para>
@@ -74,7 +74,7 @@
</sect2>
</sect1>
<sect1 id="view-scope">
<title>viewScope</title>
<title>View scope</title>
<para>
A view-state allocates a new <code>viewScope</code> when it enters.
This scope may be referenced within the view-state to assign variables that should live for the duration of the state.
@@ -103,7 +103,7 @@
</programlisting>
</sect2>
<sect2 id="view-scope-ajax">
<title>Manipulating objects view scope</title>
<title>Manipulating objects in view scope</title>
<para>
Objects in view scope are often manipulated over a series of requests from the same view.
The following example illustrates paginiation through a search results list.
@@ -128,7 +128,7 @@
</sect2>
</sect1>
<sect1 id="view-on-render">
<title>on-render</title>
<title>Executing render actions</title>
<para>
Use the <code>on-render</code> element to execute one or more actions before view rendering.
Render actions are executed on the initial render as well as any subsequent refreshes, including any partial re-renderings of the view.
@@ -140,7 +140,7 @@
</programlisting>
</sect1>
<sect1 id="view-model">
<title>Model binding</title>
<title>Binding to a model</title>
<para>
Use the <code>model</code> attribute to declare a model object the view binds to.
This attribute is typically used with views that render data controls, such as forms.
@@ -168,7 +168,7 @@
</para>
</sect1>
<sect1 id="view-bind">
<title>bind</title>
<title>Suppressing binding</title>
<para>
Use the <code>bind</code> attribute to suppress model binding and validation for particular view events.
</para>
@@ -180,7 +180,7 @@
</programlisting>
</sect1>
<sect1 id="view-validate">
<title>Validation</title>
<title>Validating a model</title>
<para>
Model validation is driven by constraints specified against the model object.
These constraints may be specified declaratively, or enforced using a programmatic validation routine or external <code>Validator</code>.
@@ -240,7 +240,7 @@ public class BookingValidator {
</sect2>
</sect1>
<sect1 id="simple-event-handlers">
<title>Event handlers</title>
<title>Handling events</title>
<para>
From a view-state, transitions without targets can also be defined. Such transitions are called "event handlers":
</para>
@@ -254,7 +254,7 @@ public class BookingValidator {
They simply execute their actions and re-render the current view or one or more fragments of the current view.
</para>
<sect2 id="event-handlers-render">
<title>Partial re-rendering</title>
<title>Rendering partials</title>
<para>
Use the <code>render</code> element to request partial re-rendering of a view after handling an event:
</para>
@@ -274,7 +274,7 @@ public class BookingValidator {
</sect2>
</sect1>
<sect1 id="view-messages">
<title>Messages</title>
<title>Working with messages</title>
<para>
Spring Web Flow's <code>MessageContext</code> is an API for recording messages during the course of flow executions.
Plain text messages can be added to the context, as well as internationalized messages resolved by a Spring <code>MessageSource</code>.
@@ -303,7 +303,7 @@ context.addMessage(builder.info().code("reservationConfirmation").build());
</programlisting>
</sect2>
<sect2 id="message-bundles">
<title>Flow message bundles</title>
<title>Using message bundles</title>
<para>
Internationalized messages are defined in message bundles accessed by a Spring <code>MessageSource</code>.
To create a flow-specific message bundle, simply define <code>messages.properties</code> file(s) in your flow's directory.
@@ -318,7 +318,7 @@ reservationConfirmation=We have processed your reservation - thank you and enjoy
</sect2>
</sect1>
<sect1 id="view-popup">
<title>popup</title>
<title>Displaying popups</title>
<para>
Use the <code>popup</code> attribute to render a view in a modal popup dialog:
</para>