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

RESOLVED - issue SWF-349: Fix several Web Flow reference manual typos

Browse Source 
http://opensource.atlassian.com/projects/spring/browse/SWF-349
This commit is contained in:
Keith Donald
2007-08-15 19:57:59 +00:00
parent c2e0e1e7d8
commit 8c2043acf9
8 changed files with 152 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
spring-webflow/changelog.txt
View File

@@ -15,6 +15,9 @@ Package org.springframework.webflow.execution
* Made the Event class non-final to allow for extension (SWF-330).
* Now allow multiple conversation containers per session in a manner that supports use in a cluster (SWF-378).
Package reference-manual
* Improved readability of reference manual in several sections (SWF-349).
Changes in version 1.0.4 (13.06.2007)
-------------------------------------

143
spring-webflow/docs/reference/src/flow-definition.xml
View File

@@ -102,7 +102,7 @@
</row>
<row>
<entry>variables</entry>
<entry>The set of flow variables to create each time an execution of the flow is started.</entry>
<entry>The set of flow instance variables to create each time an execution of the flow is started.</entry>
<entry>
<emphasis>0..*</emphasis>
</entry>
@@ -111,7 +111,7 @@
<row>
<entry>inputMapper</entry>
<entry>
The service responsible for mapping flow input provided by a caller each time an
The service responsible for mapping flow input provided by the client each time an
execution of the flow is started.
</entry>
<entry>
@@ -138,8 +138,7 @@
<row>
<entry>outputMapper</entry>
<entry>
The service responsible for mapping flow output to expose to the caller each time an
execution of the flow ends.
The service responsible for mapping flow output to expose to the client each time an execution of the flow ends.
</entry>
<entry>
<emphasis>0..1</emphasis>
@@ -242,7 +241,8 @@
<literal>org.springframework.webflow.engine.builder</literal> package.
The XML Flow Builder and <literal>spring-webflow.xsd</literal> schema are located
within the <literal>org.springframework.webflow.engine.builder.xml</literal> package.
The XML-based format is the most popular way to define flows.
The XML-based format is currently the most popular way to define flows, though
Groovy-based and Java-based formats are emerging.
</para>
</sect2>
</sect1>
@@ -414,7 +414,7 @@
<para>
Recall that all TransitionableStates have a set of one or more transitions, each defining a
path to another state in the flow (or a recursive path back to the same state).
When a transitionable state is entered it executes a behavior.
When a transitionable state is entered, it executes a behavior.
For example, a transitionable state called "Display Form" may display a form to the user
and wait for user input. The outcome of the state's execution, called an event, is used to drive execution of
one of the state's transitions. For example, the user may press the form submit button which
@@ -520,13 +520,12 @@
<sect2 id="transition-actioncriteria">
<title>Action transition execution criteria</title>
<para>
In the XML transition template above note the support for the <literal>action</literal> element within the <literal>transition</literal> element.
In the XML transition template above, note the support for the <literal>action</literal> element within the <literal>transition</literal> element.
</para>
<para>
A transition may be configured with one or more actions that execute <emphasis>before</emphasis> the transition itself
executes as <literal>executionCriteria</literal>. If one or more of these
actions do not complete successfully the transition will <emphasis>not</emphasis> be allowed.
This <emphasis>action transition criteria</emphasis> makes it possible to execute arbitrary logic
executes. If one or more of these actions do not complete successfully, the transition will <emphasis>not</emphasis> be allowed.
This <emphasis>execution criteria</emphasis> makes it possible to execute arbitrary logic
after a transition is matched but before it is executed. This is useful when you want to execute
event post-processing logic. A good example is executing form data binding and validation behavior
after a form submit event.
@@ -535,15 +534,14 @@
<sect2 id="transition-dynamic">
<title>Dynamic transitions</title>
<para>
A transition's target state resolver can be configured to dynamically calculate the
target state. For example:
A transition's target state resolver can be configured to dynamically calculate the target state. For example:
</para>
<programlisting>
&lt;transition on="back" to="${flowScope.lastStateId}" /&gt;
&lt;transition on="back" to="${flowScope.lastViewStateId}" /&gt;
</programlisting>
<para>
This will transition the flow to the state resolved by evaluating the
<literal>flowScope.lastStateId</literal> expression.
<literal>flowScope.lastViewStateId</literal> expression.
</para>
</sect2>
<sect2 id="transition-global">
@@ -555,9 +553,9 @@
transitions are called <emphasis>global transitions</emphasis>.
</para>
<para>
When an event is signaled in a transitionable state the state will first try and
match one of its own transitions. If there is no match at the state level the set of
global transitions will be tested. If there still is no match
When an event is signaled in a transitionable state, the state will first try and
match one of its own transitions. If there is no match at the state level, the set of
global transitions will be tested. If there still is no match,
a <literal>NoMatchingTransitionException</literal> will be thrown.
</para>
<para>
@@ -598,7 +596,7 @@
&lt;/flow&gt;
</programlisting>
<para>
In this mock example <literal>state1</literal> defines one transition and also inherits
In this mock example, <literal>state1</literal> defines one transition and also inherits
the two others defined within the <literal>global-transitions</literal> element.
Any other states defined within this flow would also inherit those global
transitions.
@@ -651,7 +649,7 @@
&lt;/flow&gt;
</programlisting>
<para>
In this example <literal>state1</literal> defines one transition and an exception handler
In this example, <literal>state1</literal> defines one transition and an exception handler
which executes a transition to <literal>state3</literal> if a <literal>MyBusinessException</literal>
is thrown within the state. The handled exception will be put into flash scope using the
key "stateException". That way it is available for processing in the flow or display in a view.
@@ -694,7 +692,7 @@
<sect2 id="viewState">
<title>ViewState</title>
<para>
When entered a view state allows the user (or other external client) to participate
When entered, a view state allows the user (or other external client) to participate
in a flow. This participation process goes as follows:
<orderedlist>
<listitem>
@@ -717,7 +715,7 @@
</listitem>
<listitem>
<para>
After some 'think time' the user signals an input event to resume the flow execution
After some 'think time', the user signals an input event to resume the flow execution
from the 'paused' point.
</para>
</listitem>
@@ -725,8 +723,8 @@
</para>
<para>
Spring Web Flow gives you full control over the view selection process and, on resume,
how a view state responds to a user input event. It's important to understand that Spring Web Flow is <emphasis>not</emphasis>
responsible for response rendering--as a controller, a flow makes a <emphasis>logical</emphasis> view selection when user input is required,
how a view state responds to a user input event. Spring Web Flow is currently <emphasis>not</emphasis>
concerned with rendering the actual response; as a controller, a flow makes a <emphasis>logical</emphasis> view selection when user input is required,
where a view selection serves as a response instruction. It is up to the calling system to interpret that instruction to issue a
response suitable for the environment in which the flow is executing.
</para>
@@ -797,12 +795,12 @@
<entry>FlowExecutionRedirect</entry>
<entry>
Requests a redirect back to the ViewState at a unique <emphasis>flow execution URL</emphasis>.
When this URL is accessed on subsequent requests an ApplicationView will be reconstituted and rendered.
When this URL is accessed on subsequent requests, an ApplicationView will be reconstituted and rendered.
The URL is refreshable while the flow execution remains active.
<note>
<para>
Multiple flow execution URLs may be generated for a single logical user conversation.
In that case each flow execution URL provides access to the conversation
In that case, each flow execution URL provides access to the conversation
from a previous point (ViewState). Accessing the URL refreshes the execution
from that point.
</para>
@@ -1005,17 +1003,15 @@
Browser navigational buttons may be used freely without browser warnings.
</para>
<para>
Later in this document the execution attribute <literal>alwaysRedirectOnPause</literal> is discussed,
which enforces this pattern by default. In that case each time a view state is entered
a redirect is always performed--<emphasis>automatically</emphasis>.
The execution attribute <literal>alwaysRedirectOnPause</literal>, which enforces this pattern by default,
is discussed later in this document. In that case, each time a view state is entered a redirect is always performed.
</para>
</sect4>
</sect3>
<sect3 id="viewStateJava-redirect">
<title>ViewState API - flow execution redirect</title>
<para>
The following example shows the equivalent view state definition using
the FlowBuilder API:
The following example shows the equivalent view state definition using the FlowBuilder API:
</para>
<programlisting>
public class SearchFlowBuilder extends AbstractFlowBuilder {
@@ -1032,7 +1028,7 @@
<title>ViewState XML - null view</title>
<para>
The following example illustrates a <literal>view-state</literal> definition in XML that makes a
null view selection when entered, which causes no additional response to be issued.
null view selection when entered. This causes no additional response to be issued.
</para>
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
@@ -1059,9 +1055,9 @@
<title>FlowDefinitionRedirect and ExternalRedirect</title>
<para>
The <literal>FlowDefinitionRedirect</literal> and <literal>ExternalRedirect</literal> are not
normally used with a view state. Instead they're used in an end state to continue with another,
independent flow or to redirect to an external URL. Examples are provided in the discussion of the
end state.
generally used by a view state. They are typically used by an end state, either to start
a new independent flow or redirect to an arbitrary external URL.
Examples are provided in the discussion of the end state.
</para>
</sect3>
<sect3 id="viewStateXml-formState">
@@ -1184,12 +1180,12 @@
As outlined, the <literal>ActionState</literal> is the dedicated state type for invoking one
or more actions and responding to their result to drive a state transition. There are
also other points within the lifecycle of a flow where a chain of actions can be executed.
At all of these points the only requirement is that these actions implement the central
At all of these points, the only requirement is that these actions implement the central
<literal>org.springframework.webflow.execution.Action</literal> interface.
</para>
<table>
<title>
Other points in a Flow where an Action can be executed and how those points
Other points in a Flow where an Action can be executed, and how those points
can be defined in a XML-based Flow definition.
</title>
<tgroup cols="3">
@@ -1264,7 +1260,7 @@
<para>
<note>
<para>
The above other points in a flow where actions may be executed do not
The other points above where actions may be executed do not
allow you to execute a state transition in response to the action result event.
If you need such flow control you must execute the action from within an action state.
</para>
@@ -1280,8 +1276,7 @@
the action's execution in a specific usage context.
</para>
<para>
Support for setting several common attributes is provided for convenience. These
include:
Support for setting several common attributes is provided for convenience. These include:
</para>
<table>
<title>Common Action attributes</title>
@@ -1298,7 +1293,7 @@
<row>
<entry>caption</entry>
<entry>
A short description about the action, suitable for display as a tooltip.
A short description about the action, suitable for display as a tool-tip.
</entry>
</row>
<row>
@@ -1743,8 +1738,8 @@
<para>
This state definition reads "<emphasis>if the <literal>calculateShippingMethod</literal> method on the
<literal>shippingService</literal> returns <literal>BASIC</literal> for the current order, transition to the <literal>enterBasicShippingDetails</literal>
state. If the return value is <literal>EXPRESS</literal> transition to the <literal>enterExpressShippingDetails</literal> state.
If the return value is <literal>NONE</literal> transition to the <literal>placeOrder</literal> state</emphasis>."
state. If the return value is <literal>EXPRESS</literal>, transition to the <literal>enterExpressShippingDetails</literal> state.
If the return value is <literal>NONE</literal>, transition to the <literal>placeOrder</literal> state</emphasis>."
</para>
</sect3>
<sect3 id="actionStateXml-evaluateaction">
@@ -1773,7 +1768,7 @@
&lt;/flow&gt;
</programlisting>
<para>
This state definition reads "<emphasis>evaluate the <literal>flowScope.interview.nextQuestion()</literal> expression
This state definition reads "<emphasis>evaluate the <literal>flowScope.interview.nextQuestion()</literal> expression,
and expose the result under name <literal>question</literal> in the default scope.</emphasis>"
</para>
<para>
@@ -1812,8 +1807,8 @@
</programlisting>
<para>
This flow definition reads "<emphasis>display the <literal>fileUploadForm</literal>.
On form <literal>submit</literal> invoke the <literal>uploadFile</literal> method
on the <literal>uploadAction</literal>. On <literal>success</literal> allow the user
On form <literal>submit</literal>, invoke the <literal>uploadFile</literal> method
on the <literal>uploadAction</literal>. On <literal>success</literal>, allow the user
to select another file to upload. Report that the last file was uploaded successfully by
setting the <literal>fileUploaded</literal> attribute in <literal>flash</literal> scope to
<literal>true</literal>.</emphasis>
@@ -1821,7 +1816,7 @@
<note>
<para>
Flash scoped attributes are preserved until the next user event is signaled into
the flow execution. In this example this means the <literal>fileUploaded</literal>
the flow execution. In this example, this means the <literal>fileUploaded</literal>
attribute is preserved across a redirect to the <literal>selectFile</literal>
view state and any subsequent browser refreshes. Only when the <literal>submit</literal>
event is signaled will the flash scope be cleared.
@@ -1975,7 +1970,7 @@
pre-calculated value to decide what step of the flow to transition to next. That is the kind of logic that
should be in a flow definition. In contrast, having the state <emphasis>itself</emphasis> embed
the business rule defining how shipping status is calculated is a misuse.
Instead, push such a calculation into application code where it belongs and <emphasis>instruct</emphasis>
Instead, push such a calculation into business application code where it belongs and <emphasis>instruct</emphasis>
the flow to invoke that code using an action.
</para>
</note>
@@ -2001,7 +1996,7 @@
</listitem>
<listitem>
<para>
A newly launched flow can be passed input attributes which it may choose
A newly launched flow can be passed input attributes, which it may choose
to map into its own local scope.
</para>
</listitem>
@@ -2015,7 +2010,7 @@
</para>
<para>
It is helpful to think of the process of calling a flow like calling a Java method. Flows can
be passed input arguments and can produce return values just like methods can. Flows are more powerful because
be passed input arguments, and can produce return values just like methods can. Flows are more powerful because
they are potentially long-running, as they can span more than one request into the server.
</para>
<para>
@@ -2142,10 +2137,9 @@
&lt;/flow&gt;
</programlisting>
<para>
This subflow state definition reads "<emphasis>spawn the <literal>shipping</literal> flow
and pass it the value of the <literal>shipping</literal> property on the <literal>order</literal>
object in flow scope as an input attribute with the name <literal>shipping</literal>.
When the <literal>shipping</literal> flow ends, respond to the <literal>finish</literal>
This subflow state definition reads "<emphasis>spawn the <literal>shipping</literal> flow,
passing it the value of the <literal>shipping</literal> property on the <literal>order</literal>
object in flow scope. When the <literal>shipping</literal> flow ends, respond to the <literal>finish</literal>
result event by transitioning to the <literal>placeOrder</literal> state</emphasis>."
</para>
<note>
@@ -2182,10 +2176,15 @@
<sect3 id="flowInputMapping">
<title>Flow input mapping - input contract</title>
<para>
Internally within the definition of the <literal>shipping</literal> flow referenced above, the flow
may choose to map the <literal>shipping</literal> input attribute into its own scope using
its input mapper when it starts. Any input attributes must be explictly mapped, defining the input
contract for the flow:
Within a flow definition, input attributes can be obtained by configuring an input-mapper.
Any input attributes must be explictly mapped.
The list of permitted input attributes defines the input contract for the flow.
<tip>
<para>
If you think of calling a Flow as analogous to calling a Java method, it
is helpful to think of input-attributes as analogous to method arguments.
</para>
</tip>
</para>
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
@@ -2204,8 +2203,8 @@
&lt;/flow&gt;
</programlisting>
<para>
This short-form input mapper declaration reads "<emphasis>when a new execution of this flow starts
map the <literal>shipping</literal> input attribute into <literal>flowScope</literal> under
This short-form input mapper declaration reads "<emphasis>when a new execution of this flow starts,
map the provided <literal>shipping</literal> input attribute into <literal>flowScope</literal> under
the name <literal>shipping</literal></emphasis>."
</para>
<note>
@@ -2223,19 +2222,19 @@
flow outcome; for example, "finish", or "cancel".
</para>
<para>
If the ended flow was acting as a top-level or <emphasis>root flow</emphasis> the
entire flow execution ends and cannot be resumed. In this case the end state is responsible
If the ended flow was acting as a top-level or <emphasis>root flow</emphasis>, the
entire flow execution ends and cannot be resumed. In this case, the end state is responsible
for making a <literal>ViewSelection</literal> that is the basis for the ending response (for example,
a confirmation page, or a redirect request to another flow or an external URL).
</para>
<para>
If the ended flow was acting as a subflow, the spawned subflow session ends and
the calling parent flow <emphasis>resumes</emphasis> by responding to the end
result returned. In this case the responsibility for any <literal>ViewSelection</literal>
result returned. In this case, the responsibility for any <literal>ViewSelection</literal>
falls on the parent flow.
</para>
<para>
Once a flow ends any attributes in flow scope go out of scope immediately
Once a flow ends, any attributes in flow scope go out of scope immediately
and become eligible for garbage collection.
</para>
<para>
@@ -2258,7 +2257,7 @@
identifier of the end-state itself. For example, an end state with id <literal>finish</literal>
returns a result event with id <literal>finish</literal>. Also, any attributes in
flow scope that have been explicitly mapped as <emphasis>output attributes</emphasis>
are returned as result event parameters. This allows you to return data along
are returned as result event attributes. This allows you to return data along
with the logical flow outcome.
</para>
<para>
@@ -2329,7 +2328,7 @@
&lt;/flow&gt;
</programlisting>
<para>
This end state definition reads "<emphasis>terminate the <literal>order</literal> flow
This end state definition reads "<emphasis>terminate the <literal>order</literal> flow,
and redirect to a new execution of the <literal>searchFlow</literal></emphasis>".
</para>
</sect3>
@@ -2355,14 +2354,14 @@
&lt;/flow&gt;
</programlisting>
<para>
This end state definition reads "<emphasis>terminate the <literal>order</literal> flow
This end state definition reads "<emphasis>terminate the <literal>order</literal> flow,
and redirect to the URL returned by evaluating the <literal>/orders/${flowScope.order.id}</literal>
expression</emphasis>."
</para>
<para>
This is an example of the familiar <emphasis>redirect after post</emphasis> pattern where
after transaction completion a redirect is issued allowing the result of the transaction
to be viewed (in this case using REST-style URLs).
to be viewed (in this case using a REST-style URL).
</para>
</sect3>
<sect3 id="endStateXml-outputattribute">
@@ -2390,7 +2389,7 @@
&lt;/flow&gt;
</programlisting>
<para>
This end state definition reads "<emphasis>terminate the <literal>shipping</literal> flow
This end state definition reads "<emphasis>terminate the <literal>shipping</literal> flow,
and expose the <literal>shipping</literal> property in flow scope as an output attribute
with name <literal>shipping</literal></emphasis>."
</para>
@@ -2412,7 +2411,7 @@
}
</programlisting>
<para>
Since this end-state does not make a view selection it is expected this flow will be always used
Since this end-state does not make a view selection, it is expected this flow will be always used
as a subflow. When this flow ends, the calling parent flow is expected to respond to the
<literal>finish</literal> result, and may choose to map the <literal>shipping</literal> output
attribute into its own scope.
@@ -2422,7 +2421,7 @@
<title>SubflowState XML - mapping an output attribute</title>
<para>
The next example shows how a <literal>subflow-state</literal> can respond to the ending
result of a subflow and map output attributes into its own scope:
result of a subflow, and map subflow output attributes into its own scope:
</para>
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
@@ -2449,14 +2448,14 @@
</programlisting>
<para>
This subflow state definition reads "<emphasis>spawn the <literal>shipping</literal> flow
as a subflow. When the <literal>shipping</literal> flow ends map the <literal>shipping</literal> output
as a subflow. When the <literal>shipping</literal> flow ends, map the <literal>shipping</literal> output
attribute into flow scope under the name <literal>shipping</literal>, then respond to
the <literal>finish</literal> result event by transitioning to
the <literal>placeOrder</literal> state</emphasis>."
</para>
<note>
<para>
Had this output mapping not been defined the shipping attribute made available as output
Had this output mapping not been defined, the shipping attribute made available as output
to this flow by the ending subflow would have been ignored.
</para>
</note>

30
spring-webflow/docs/reference/src/flow-execution-repository.xml
View File

@@ -15,12 +15,12 @@
challenges, as there must exist a stable mechanism for a new request to be associated
with an existing execution in the view state that matches what the user expects. This problem
is more difficult when you consider that many applications require use of browser
navigational buttons and their use involves updating local history without
navigational buttons, and use of these buttons involves updating local history without
notifying the server.
</para>
<para>
The problem of flow execution persistence is addressed by Spring Web Flow's <emphasis>flow
execution repository subsystem</emphasis>. In this chapter you will learn how to use the system
execution repository subsystem</emphasis>. In this chapter, you will learn how to use the system
to manage the storage of active web conversations in a stable manner.
</para>
</sect1>
@@ -34,9 +34,9 @@
<listitem>
<para>
When a flow execution reaches a <literal>ViewState</literal> it is said to have <emphasis>paused</emphasis>,
where it waits in that state for user input to be provided so it can continue. After pausing the
where it waits in that state for user input to be provided so it can continue. After pausing, the
<literal>ViewSelection</literal> returned is used to issue a response to the user
that provides a vehicle for collecting the required input.
that provides a vehicle for collecting the required user input.
</para>
</listitem>
<listitem>
@@ -49,7 +49,7 @@
</orderedlist>
</para>
<para>
Each time an active flow execution is <emphasis>paused</emphasis> it is saved out to a
Each time an active flow execution is <emphasis>paused</emphasis>, it is saved out to a
repository. When the next request comes in for that flow execution, it is restored
from the repository, <emphasis>resumed</emphasis>, and continued. This process continues
until the flow execution reaches an end state, at which time it is removed from the repository.
@@ -83,11 +83,11 @@
<sect1 id="repository-entry-identity">
<title>Flow execution identity</title>
<para>
When a flow execution is created it marks the start of a new conversation between a browser
and the server. As outlined, a new flow execution that is still active after startup
When a new flow execution is created, it marks the start of a new conversation between a browser
and the server. A new flow execution that is still active after startup
processing indicates the start of a conversation that will span more than one request
and needs to be persisted. When this is the case, that flow execution is assigned
an <emphasis>persistent identifer</emphasis> by the repository. By default the
an <emphasis>persistent identifer</emphasis> by the repository. By default, the
structure of this identifier consists of a two-part composite key. This key is used
by clients to restore the flow execution on subsequent requests.
</para>
@@ -114,21 +114,21 @@
Together the conversation id plus the continuation id make up the unique two-part
<emphasis>flow execution key</emphasis> that identifies a state
of a conversation <emphasis>at a point in time</emphasis>. By submitting this key
in a subsequent request a browser can restore the conversation at that point
in a subsequent request, a browser can restore the conversation at that point
and <emphasis>continue</emphasis> from there.
</para>
<para>
So on a subsequent request the conversation is resumed by restoring a flow execution
from the repository using the two-part key. After event processing if the
So on a subsequent request, the conversation is resumed by restoring a flow execution
from the repository using the two-part key. After event processing, if the
flow execution is still active it is saved back out to the repository.
At this time a new flow execution key is generated. By default that key
At this time a new flow execution key is generated. By default, that key
retains the same <emphasis>conversation identifier</emphasis>, as the same logical
conversation is in progress; however the <emphasis>continuation identifier</emphasis>
changes to provide an index into the state of the flow execution
at <emphasis>this new point in time</emphasis>.
</para>
<para>
By submitting this new key in a subsequent request a browser can
By submitting this new key in a subsequent request, a browser can
restore the conversation at that point and <emphasis>continue</emphasis> from there.
This process continues until a flow execution reaches an end state during event processing
signaling the end of the conversation.
@@ -144,8 +144,8 @@
resulting in any flow execution continuations associated with the conversation being purged.
</para>
<para>
Once a conversation has been ended the conversation identifier is no longer valid
and cannot ever be used again.
Once a conversation has ended, the conversation identifier is no longer valid
and can never be used again.
</para>
</sect1>
<sect1 id="repository-implementations">

45
spring-webflow/docs/reference/src/flow-execution.xml
View File

@@ -4,14 +4,14 @@
<sect1 id="execution-intro">
<title>Introduction</title>
<para>
Once a flow has been defined any number of executions of it can be launched in parallel
Once a flow has been defined, any number of executions of it can be launched in parallel
at runtime. Execution of a flow is carried out by a dedicated system that
is based internally on a state machine that runs atop the Java VM. As the life of a
flow execution can span more than one request into the server, this system
is also responsible for persisting execution state across requests.
</para>
<para>
This chapter documents Spring Web Flow's flow execution system. You'll
This chapter documents Spring Web Flow's flow execution system. You will
learn the core constructs of the system and how to execute flows out-of-container
within a JUnit test environment.
</para>
@@ -20,9 +20,9 @@
<title>FlowExecution</title>
<para>
A <literal>org.springframework.webflow.execution.FlowExecution</literal> is a runtime instantiation of a flow definition.
Given a single <literal>FlowDefinition</literal> any
number of independent flow executions may be created, typically by a
<literal>FlowExecutionFactory</literal>.
Given a single <literal>FlowDefinition</literal>, any
number of independent flow executions may be created.
These executions are typically created by a <literal>FlowExecutionFactory</literal>.
</para>
<para>
A flow execution carries out the execution of program instructions defined within
@@ -30,7 +30,7 @@
</para>
<para>
<emphasis>
It may be helpful to think of a flow definition as analagous to a Java <literal>Class</literal> and a
It may be helpful to think of a flow definition as analagous to a Java <literal>Class</literal>, and a
flow execution as analagous to an object instance of that <literal>Class</literal>. Signaling
an execution event can be considered analagous to sending an object a message.
</emphasis>
@@ -44,8 +44,8 @@
</programlisting>
<para>
Once created, a new flow execution is initially inactive, waiting to be started. Once
started a flow execution becomes active by entering its <literal>startState</literal>.
From there it continues executing until it enters a state where user input is required
started, a flow execution becomes active by entering its <literal>startState</literal>.
From there, it continues executing until it enters a state where user input is required
to continue or it terminates.
</para>
</sect2>
@@ -57,10 +57,10 @@
ViewSelection startingView = execution.start(input, context);
</programlisting>
<para>
When a flow execution reaches a state where input is required to continue it is said to have <emphasis>paused</emphasis>,
where it waits in that state for the input to be provided. After pausing the
<literal>ViewSelection</literal> returned is typically used to issue a response to the user
that provides a vehicle for collecting the required input.
When a flow execution reaches a state where input is required to continue, it is said to have <emphasis>paused</emphasis>,
where it waits in that state for user input to be provided. After pausing, the
<literal>ViewSelection</literal> returned is used to issue a response to the user
that provides a vehicle for collecting the required user input.
</para>
<para>
User input is provided by <emphasis>signaling an event</emphasis> that
@@ -69,7 +69,7 @@
resumes by consuming the event.
</para>
<para>
Once a flow execution has resumed it continues executing until it again enters a
Once a flow execution has resumed, it continues executing until it again enters a
state where more input is needed or it terminates. Once a flow execution has terminated
it becomes inactive and cannot be resumed.
</para>
@@ -335,8 +335,7 @@
the session at the top of the stack.
</para>
<para>
The contextual properties associated with a <literal>FlowSession</literal>
are summarized below:
The contextual properties associated with a <literal>FlowSession</literal> are summarized below:
</para>
<table>
<title>Flow Session properties</title>
@@ -422,7 +421,7 @@
</caption>
</mediaobject>
<para>
In this illustration a flow execution has been created for the <literal>Book Flight</literal> flow.
In this illustration, a flow execution has been created for the <literal>Book Flight</literal> flow.
The execution is currently active and the <literal>activeSession</literal> indicates it
is in the <literal>Display Seating Chart</literal> state of the <literal>Assign Seats</literal> flow,
which was spawned as a subflow from the <literal>Enter Seat Assignments</literal> state.
@@ -488,7 +487,7 @@
Spring Web Flow provides support within the <literal>org.springframework.webflow.test</literal>
package for testing flow executions with JUnit. This support is provided as convenience but is
entirely optional, as a flow execution is instantiable in any environment with the standard
<literal>new</literal> operator.
Java <literal>new</literal> operator.
</para>
<para>
The general strategy for testing flows follows:
@@ -595,13 +594,13 @@
</listitem>
<listitem>
<para>
On form submit and successful data binding and validation the search is executed.
On form submit and successful data binding and validation, the search is executed.
After search execution a results view is displayed.
</para>
</listitem>
<listitem>
<para>
From the results view the user may select a result they wish to browse additional details on
From the results view, the user may select a result they wish to browse additional details on
or they may request a new search. On select, the "detail" flow is spawned and
when it finishes the search is re-executed and it's results redisplayed.
</para>
@@ -641,7 +640,7 @@
</listitem>
</orderedlist>
<para>
To assist with writing these assertions Spring Web Flow ships with JUnit-based flow execution
To assist with writing these assertions, Spring Web Flow ships with JUnit-based flow execution
test support within the <literal>org.springframwork.webflow.test</literal> package.
These base test classes are indicated below:
</para>
@@ -741,9 +740,9 @@
}
</programlisting>
<para>
With a well-written flow execution test passing that covers the controller behavior scenarios
possible for your flow you have concrete evidence the flow will execute as expected when
deployed in a container.
With a well-written flow execution test passing that exercises the scenarios
possible for your flow, you have concrete evidence the flow will execute as expected when
deployed into a container.
</para>
<mediaobject>
<imageobject role="fo">

50
spring-webflow/docs/reference/src/flow-executor.xml
View File

@@ -9,7 +9,7 @@
across a variety of environments.
</para>
<para>
In this chapter you'll learn how to execute flows within Spring MVC, Struts,
In this chapter, you will learn how to execute flows within Spring MVC, Struts,
and Java Server Faces (JSF) based applications.
</para>
</sect1>
@@ -48,19 +48,19 @@
<para>
Request that the last response issued by a flow execution be re-issued.
Unlike start and signalEvent, the refresh operation is an idempotent operation
that does not affect the state of a flow execution.
that does not change the state of a flow execution.
</para>
</listitem>
</orderedlist>
</para>
<para>
Each operation accepts an <literal>ExternalContext</literal> that provides normalized
access to properties of an external system that has called into Spring Web Flow, allowing
access to environment-specific request parameters as well as request, session, and
application-level attributes.
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.
</para>
<para>
Each operation returns a <literal>ResponseInstruction</literal> which the calling system is
Each operation returns a <literal>ResponseInstruction</literal>, which the calling system is
expected to use to issue a suitable response.
</para>
<para>
@@ -81,7 +81,7 @@
As you can see, an <literal>ExternalContext</literal> implementation exists 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 special case.
specific implementation. The need for such downcasting is considered a corner case.
</para>
<sect2 id="flowexecutor-impl">
<title>FlowExecutorImpl</title>
@@ -233,8 +233,7 @@
The <literal>alwaysRedirectOnPause</literal> attribute determines if
a flow execution redirect occurs automatically each time an execution pauses
(automated <literal>POST+REDIRECT+GET</literal> behavior).
Setting this attribute to false will disable the <emphasis>default 'true' behavior</emphasis>
where a flow execution redirect always occurs on pause.
Setting this attribute to false will disable the <emphasis>default 'true' behavior</emphasis>.
</para>
</note>
</para>
@@ -303,7 +302,7 @@
core Spring Framework. Use of Portlet MVC requires Spring 2.0.
</para>
<para>
For both Servlet and Portlet MVC a <literal>FlowController</literal> acts as an adapter
For both Servlet and Portlet MVC, a <literal>FlowController</literal> acts as an adapter
between Spring MVC and Spring Web Flow. As an adapter, this controller has knowledge
of both systems and delegates to a flow executor for driving the execution of flows.
One controller typically executes all flows of an application, relying on
@@ -355,13 +354,6 @@
are extracted from an incoming controller request with the
<literal>org.springframework.webflow.executor.support.FlowExecutorArgumentExtractor</literal>
strategy.
<note>
<para>
The various flow controllers typically do not use this strategy directly but instead use a
convenient <literal>FlowExecutorArgumentHandler</literal> implementation that takes care
of argument extraction as well as exposing responsibilities (in callback URLs).
</para>
</note>
</para>
<para>
The next several examples illustrate strategies for parameterizing flow controllers
@@ -446,7 +438,7 @@
</programlisting>
<note>
<para>
In this case the <literal>eventId</literal> is determined by parsing the name of the
In this case, the <literal>eventId</literal> is determined by parsing the name of the
button that was pressed.
</para>
</note>
@@ -463,7 +455,7 @@
<para>
The request-path based argument extractor strategy relies on executor arguments
being path elements as much as possible. This results in friendlier REST-style URLs such
as <literal>http://host/app/myflow</literal> instead of
as <literal>http://host/app/myflow</literal>, instead of
<literal>http://host/app?_flowId=myflow</literal>.
</para>
<sect3 id="executor-servletmvc-pathextractor">
@@ -529,7 +521,7 @@
takes responsibility for view navigation handling and managing model state, adding power and
simplicity to JSF's default navigation system and object scopes. Plain JSF views and components continue to work just as before,
and are able to participate in flows with full access to flow state. In addition, other view technologies
such as Facelets and Ajax4JSF continue to plug-in normally.
such as Facelets continue to plug-in normally.
</para>
<para>
The JSF integration relies on custom implementations of core JSF artifacts such as the PhaseListener
@@ -566,13 +558,13 @@
<para>
The <classname>DelegatingFlowVariableResolver</classname> resolves JSF a value binding expression like {#someBean.someProperty}
to a flow execution attribute. This resolver searches flash, flow, and conversation scope in that order until
it finds a match. If no match is found this resolver delegates to the next resolver in the chain.
it finds a match. If no match is found, this resolver delegates to the next resolver in the chain.
</para>
</sect2>
<sect2 id="executor-jsf-simple-webflow-setup">
<title>Configuring the Web Flow system</title>
<para>
The artifacts defined faces-config.xml use Spring to locate the Web Flow system.
The artifacts defined in the faces-config.xml use Spring to access the Web Flow system configuration.
This requires a Spring Web Application Context to be bootstrapped using a ContextLoaderListener in
the web.xml deployment descriptor:
</para>
@@ -589,9 +581,8 @@
&lt;/listener&gt;
</programlisting>
<para>
In this example inside webflow-config.xml resides the configuration of the Web Flow system the JSF
artifacts will delegate to. A bean named <literal>flowExecutor</literal> is configured and
linked with a flow definition registry containing the flows eligible for execution:
This context should contain the Web Flow system configuration.
The example <literal>webflow-config.xml</literal> below shows a typical Web Flow configuration for a JSF environment:
</para>
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
@@ -615,7 +606,12 @@
&lt;/beans&gt;
</programlisting>
<para>
Any executor property such as the flow execution repository type is configurable here, consistent
A bean named <literal>flowExecutor</literal> must be configured and linked with a flow definition registry
that contains the flows eligible for execution. Note the <literal>flowExecutor</literal> bean name is significant,
as that is bean name the Web Flow JSF extensions will expect.
</para>
<para>
Any flow executor property such as the flow execution repository type is configurable here, consistent
with the other environments Spring Web Flow supports.
</para>
</sect2>
@@ -677,7 +673,7 @@
&lt;/flow&gt;
</programlisting>
<para>
A primary benefit of using JSF is it a rich UI component framework, and components have behaviors.
A primary benefit of using JSF is it a rich UI component framework, and UI components have both data and behavior.
As JSF components typically handle data binding and validation behaviors, the actual flow
definition logic is often simpler and more focused as a result.
</para>

4
spring-webflow/docs/reference/src/index.xml
View File

@@ -15,8 +15,8 @@
<bookinfo>
<title>Spring Web Flow</title>
<subtitle>Reference Documentation</subtitle>
<releaseinfo>Version 1.0.5-SNAPSHOT</releaseinfo>
<pubdate>April 2007</pubdate>
<releaseinfo>Version 1.0.5</releaseinfo>
<pubdate>August 2007</pubdate>
<authorgroup>
<author>
<firstname>Keith</firstname>

10
spring-webflow/docs/reference/src/overview.xml
View File

@@ -242,7 +242,7 @@
<entry>
Support for working with registries of flow definitions. Flow
definitions eligible for execution are typically stored in
a registry providing lookup services.
a registry that provides lookup services.
</entry>
<entry>
definition.registry
@@ -486,7 +486,7 @@
<sect2 id="layer-executor">
<title>The Executor Layer</title>
<para>
Stable higher-layer for driving and coordinating the execution of flow definitions.
Stable higher-level layer for driving and coordinating the execution of flow definitions.
This layer is decoupled from the more-volatile engine implementation.
</para>
<para>
@@ -513,7 +513,7 @@
<row>
<entry>Core</entry>
<entry>
Stable, generic flow executor abstractions and support.
Generic flow executor abstractions and support.
</entry>
<entry>
executor,
@@ -619,7 +619,7 @@
As described above, some subsystem packages are optional depending on your use of the
subsystem. For example, use of Spring Web Flow in a Servlet environment entails use of
the <literal>ExternalContext</literal> context.servlet package which requires the
Servlet API to be in the classpath. In this case the context.portlet package is not
Servlet API to be in the classpath. In this case, the context.portlet package is not
used and the Portlet API is not required.
</para>
</note>
@@ -633,7 +633,7 @@
<sect1 id="introduction-support">
<title>Support</title>
<para>
Spring Web Flow 1.x is supported on Spring Framework 1.2.7 or > for the 1.x series and
Spring Web Flow 1.x is supported on Spring Framework 1.2.7 or > for the 1.x series, and
supported on 2.0 or > for the 2.x series.
</para>
<para>

23
spring-webflow/docs/reference/src/practical.xml
View File

@@ -78,7 +78,7 @@
Java 1.5 (or greater) and Ant 1.6 (or greater) are prerequisites for building the sample applications.
Ensure those are present in the system path or are passed on the command line. To build Web Flow
samples from the command line, open a prompt, cd to the directory where Spring Web Flow was
unzipped and run the following:
unzipped, and run the following:
<programlisting>
cd projects/spring-webflow/build-spring-webflow
ant dist
@@ -94,15 +94,14 @@ ant dist
<title>Importing Projects into Eclipse</title>
<para>
Importing the sample projects into Eclipse is easy. With a new or an existing workspace select:
<emphasis>File &gt; Import &gt; Existing Projects into Workspace</emphasis>. In the resulting dialog browse to the project
<emphasis>File &gt; Import &gt; Existing Projects into Workspace</emphasis>. In the resulting dialog, browse to the project
subdirectory where Spring Web Flow was unzipped and choose it as the root directory to import from.
Select OK. Here Eclipse will list all projects it found including the sample application projects.
Select the projects you're interested in, and select Finish.
</para>
<para>
If you previously built each project from the command line Eclipse will compile with no errors.
If not you will need to run the Ant build <emphasis>once</emphasis> for these errors to clear
and you can do that within Eclipse.
If you previously built each project from the command line, Eclipse will compile with no errors.
If not, you will need to run the Ant build <emphasis>once</emphasis> for these errors to clear.
</para>
<para>
To build all projects inside Eclipse, import and expand the <literal>build-spring-webflow</literal> project, right-click on
@@ -145,7 +144,7 @@ ant dist
<sect2>
<title>Other IDE's</title>
<para>
Importing samples into other IDE's should be fairly straight-forward. If using another IDE
Importing samples into other IDE's should be fairly straight-forward. If using another IDE,
running the Ant build from the command line first may help as it will populate the lib
subdirectories of each sample project. Follow steps similar as those outlined for Eclipse above.
</para>
@@ -349,8 +348,8 @@ public interface SaleProcessor {
sparing the need to implement methods for all lifecycle events.
</para>
<para>
Looking inside SellItemFlowExecutionListener it implements the stateEntering
method executed whenever a new state is about to be entered.
Looking inside SellItemFlowExecutionListener, it implements the stateEntering
method executed for whenever a new state is about to be entered.
The logic in this method checks if the current web flow state
has an attribute named "role" and if so it ensures the user
has that role:
@@ -581,7 +580,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) {
<para>
The Sellitem-JSF example uses Web Flow and JSF to build a shopping
cart wizard. Navigation logic and supporting managed beans
are supplied by Spring Web Flow while UI views and
are supplied by Spring Web Flow, while UI views and
overall servlet processing is based on JSF technology.
</para>
<note>
@@ -590,7 +589,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) {
examples are very similar. To avoid repetition the documentation for
the Sellitem-JSF example focuses primarily on the points of integration between
Web Flow and JSF. For further general information on Web Flow definitions
and supporting Java classes for the Sellitem example please refer to the
and supporting Java classes for the Sellitem example, please refer to the
<link linkend="sellitem-sample">Sellitem</link> example documentation.
</para>
</note>
@@ -615,7 +614,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) {
</programlisting>
</para>
<para>
In addition the web.xml loads a Spring root web application context containing the services
In addition, the web.xml loads a Spring root web application context containing the services
used by the application:
<programlisting>
&lt;context-param&gt;
@@ -642,7 +641,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) {
<sect2>
<title>Web Flow JSF Setup in faces-config.xml</title>
<para>
To plug in Web Flow a few things must be added once to faces-config.xml.
To plug in Web Flow, a few things must be added once to faces-config.xml.
This is demonstrated in the faces-config.xml of Sellitem-JSF:
<programlisting>
&lt;application&gt;