Spring Web Flow Docs.
-----------------------
1) Defining Flows
1.1) What is a flow?
A flow encapsulates a reusable sequence of steps that can execute in different contexts.
1.2) What is the makeup of a typical flow?
In Spring Web Flow, a flow consists of a series of steps called "states". Entering a state typically results
in a view being displayed to the user. On that view, user events occur that are handled by the state.
These events can trigger transitions to other states which result in view navigations.
1.3) How are flows authored?
Flows are authored by web application developers using a simple XML-based flow definition language.
1.4) Essential language elements?
flow
Every flow begins with the following root element:
<?xml version="1.0" encoding="UTF-8"?>
<flow xmlns="http://www.springframework.org/schema/webflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/webflow
http://www.springframework.org/schema/webflow/springwebflow-2.0.xsd">
</flow>
All states of the flow are defined within this element. The first state defined becomes the flow's starting point.
view-state
Use the view-state element to define a step of the flow that renders a view:
<view-state id="enterBookingDetails" />
By convention, a view-state maps its id to a view template in the directory where the flow is located. For example,
the state above might render /WEB-INF/hotels/booking/ enterBookingDetails.xhtml if the flow itself was located in the
/WEB-INF/hotels/booking directory.
transition
Use the transition element to handle events that occur within a state:
<view-state id="enterBookingDetails">
<transition on="submit" to="reviewBooking" />
</view-state>
These transitions drive view navigations.
end-state
Use the end-state element to define a flow outcome:
<end-state id="bookingCancelled" />
When a flow transitions to a end-state it terminates and the outcome is returned.
Example:
<flow xmlns="http://www.springframework.org/schema/webflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/webflow
http://www.springframework.org/schema/webflow/springwebflow-2.0.xsd">
<view-state id="enterBookingDetails">
<transition on="submit" to="reviewBooking" />
</view-state>
<view-state id="reviewBooking">
<transition on="confirm" to="bookingConfirmed" />
<transition on="revise" to="enterBookingDetails" />
<transition on="cancel" to="bookingCancelled" />
</view-state>
<end-state id="bookingConfirmed" />
<end-state id="bookingCancelled" />
</flow>
1.5) Actions
Most flows need to express more than just view navigation logic. Typically they also need to invoke business services of the application or other actions.
Within a flow, there are several points where you can execute actions. These points are:
• On flow start
• On state entry
• On view render
• On transition execution
• On state exit
• On flow end
Actions are defined using a concise expression language. Spring Web Flow uses the Unified EL by default. The next few sections will cover the essential language elements for defining actions.
evaluate :
The action element you will use most often is the evaluate element. Use the evaluate element to evaluate an expression at a point within your flow. With this single tag you can invoke methods on Spring beans or any other flow variable. For example:
<evaluate expression="entityManager.persist(booking)" />
Assigning an evaluate result :
If the expression returns a value, that value can be saved in the flow's data model called flowScope:
<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels"/>
Converting an evaluate result :
If the expression returns a value that may need to be converted, specify the desired type using the result-type attribute:
<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" result-type="dataModel"/>
1.6) Input/Output Mapping
Each flow has a well-defined input/output contract. Flows can be passed input attributes when they start, and can return output attributes when they end.
<input name="hotelId" type="long" value="flowScope.hotelId" required="true" />
Make it input Name , type , corresponding value and is mandatory field.
<end-state id="bookingConfirmed">
<output name="bookingId" />
</end-state>
1.7) Variables
A flow may declare one or more instance variables. These variables are allocated when the flow starts. Any @Autowired transient references the variable holds are also rewired when the flow resumes.
var : Use the var element to declare a flow variable:
<var name="searchCriteria" lass="com.mycompany.myapp.hotels.search.SearchCriteria"/>
Make sure your variable's class implements java.io.Serializable, as the instance state is saved between flow requests.
Variable Scopes:
Web Flow can store variables in one of several scopes:
Flow Scope:
Flow scope gets allocated when a flow starts and destroyed when the flow ends. With the default implementation, any objects stored in flow scope need to be Serializable.
View Scope:
View scope gets allocated when a view-state enters and destroyed when the state exits. View scope is only referenceable from within a view-state. With the default implementation, any objects stored in view scope need to be Serializable.
Request Scope :
Request scope gets allocated when a flow is called and destroyed when the flow returns.
Flash Scope :
Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends.
With the default implementation, any objects stored in flash scope need to be Serializable.
Conversation Scope :
Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends.
Conversation scope is shared by a top-level flow and all of its sub flows. With the default implementation,
conversation scoped objects are stored in the HTTP session and should generally be Serializable to account
for typical session replication.
1.8) Calling Subflows :
A flow may call another flow as a subflow. The flow will wait until the subflow returns, then respond to the subflow outcome.
subflow-state
Use the subflow-state element to call another flow as a subflow:
<subflow-state id="addGuest" subflow="createGuest">
<transition on="guestCreated" to="reviewBooking">
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
</transition>
<transition on="creationCancelled" to="reviewBooking" />
</subflow-state>
Passing a subflow input : Use the input element to pass input to the subflow:
<subflow-state id="addGuest" subflow="createGuest">
<input name="booking" />
<transition to="reviewBooking" />
</subflow-state>
Mapping subflow output : Simply refer to a subflow output attribute by its name within a outcome transition:
<transition on="guestCreated" to="reviewBooking">
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
</transition>
Final Example :
<flow xmlns="http://www.springframework.org/schema/webflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/webflow
http://www.springframework.org/schema/webflow/springwebflow-
2.0.xsd">
<input name="hotelId" />
<on-start>
<evaluate expression="bookingService.createBooking(hotelId, currentUser.name)" result="flowScope.booking" />
</on-start>
<view-state id="enterBookingDetails">
<transition on="submit" to="reviewBooking" />
</view-state>
<view-state id="reviewBooking">
<transition on="addGuest" to="addGuest" />
<transition on="confirm" to="bookingConfirmed" />
<transition on="revise" to="enterBookingDetails" />
<transition on="cancel" to="bookingCancelled" />
</view-state>
<subflow-state id="addGuest" subflow="createGuest">
<transition on="guestCreated" to="reviewBooking">
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
</transition>
<transition on="creationCancelled" to="reviewBooking" />
</subflow-state>
<end-state id="bookingConfirmed" >
<output name="bookingId" value="booking.id" />
</end-state>
<end-state id="bookingCancelled" />
</flow>
2) Expression Language (EL) :
EL is used for many things within a flow including:
1. Access client data such as declaring flow inputs or referencing request parameters.
2. Access data in Web Flow's RequestContext such as flowScope or currentEvent.
3. Invoke methods on Spring-managed objects through actions.
4. Resolve expressions such as state transition criteria, subflow ids, and view names.
2.1) Expression types :
Standard Expressions: The first and most common type of expression is the standard expression. Such expressions are evaluated directly by the EL and need not be enclosed in delimiters like #{}. Ex : <evaluate expression="searchCriteria.nextPage()" />
Template expressions : The second type of expression is a template expression. A template expression allows mixing of literal text with one or more standard expressions. Each standard expression block is explicitly surrounded with the #{} delimiters.
For example: <view-state id="error" view="error-#{externalContext.locale}.xhtml" />
List of implicit variables:
1) flowScope : Use flowScope to assign a flow variable. Flow scope gets allocated when a flow starts and destroyed when the flow ends. With the default implementation, any objects stored in flow scope need to be Serializable.
<evaluate expression="searchService.findHotel(hotelId)" result="flowScope.hotel" />
2) viewScope : Use viewScope to assign a view variable. View scope gets allocated when a view-state enters and destroyed when the state exits. View scope is only referenceable from within a view-state. With the default implementation, any objects stored in view scope need to be Serializable.
<on-render>
<evaluate expression="searchService.findHotels(searchCriteria)" result="viewScope.hotels"
result-type="dataModel" />
</on-render>
3) requestScope : Use requestScope to assign a request variable. Request scope gets allocated when a flow is called and destroyed when the flow returns.
<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
4) flashScope : Use flashScope to assign a flash variable. Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends. With the default implementation, any objects stored in flash scope need to be Serializable.
<set name="flashScope.statusMessage" value="'Booking confirmed'" />
5) conversationScope : Use conversationScope to assign a conversation variable. Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends. Conversation scope is shared by a top-level flow and all of its subflows. With the default implementation, conversation scoped objects are stored in the HTTP session and should generally be Serializable to account for typical session replication.
<evaluate expression="searchService.findHotel(hotelId)" result="conversationScope.hotel" />
6) requestParameters: Use requestParameters to access a client request parameter:
<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
7) currentEvent : Use currentEvent to access attributes of the current Event:
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
8) currentUser: Use currentUser to access the authenticated Principal:
<evaluate expression="bookingService.createBooking(hotelId, currentUser.name)"
result="flowScope.booking" />
9) messageContext : Use messageContext to access a context for retrieving and creating flow execution messages, including error and success messages. See the MessageContext Javadocs for more information.
<evaluate expression="bookingValidator.validate(booking, messageContext)" />
10) resourceBundle : Use resourceBundle to access a message resource.
<set name="flashScope.successMessage" value="resourceBundle.successMessage" />
11) flowRequestContext : Use flowRequestContext to access the RequestContext API, which is a representation of the current flow request. See the API Javadocs for more information.
12) flowExecutionContext : Use flowExecutionContext to access the FlowExecutionContext API, which is a representation of the current flow state. See the API Javadocs for more information.
13) flowExecutionUrl : Use flowExecutionUrl to access the context-relative URI for the current flow execution view-state.
14) externalContext :Use externalContext to access the client environment, including user session attributes.
<evaluate expression="searchService.suggestHotels(externalContext.sessionMap.userProfile)"
result="viewScope.hotels" />
-----------------------
1) Defining Flows
1.1) What is a flow?
A flow encapsulates a reusable sequence of steps that can execute in different contexts.
1.2) What is the makeup of a typical flow?
In Spring Web Flow, a flow consists of a series of steps called "states". Entering a state typically results
in a view being displayed to the user. On that view, user events occur that are handled by the state.
These events can trigger transitions to other states which result in view navigations.
1.3) How are flows authored?
Flows are authored by web application developers using a simple XML-based flow definition language.
1.4) Essential language elements?
flow
Every flow begins with the following root element:
<?xml version="1.0" encoding="UTF-8"?>
<flow xmlns="http://www.springframework.org/schema/webflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/webflow
http://www.springframework.org/schema/webflow/springwebflow-2.0.xsd">
</flow>
All states of the flow are defined within this element. The first state defined becomes the flow's starting point.
view-state
Use the view-state element to define a step of the flow that renders a view:
<view-state id="enterBookingDetails" />
By convention, a view-state maps its id to a view template in the directory where the flow is located. For example,
the state above might render /WEB-INF/hotels/booking/ enterBookingDetails.xhtml if the flow itself was located in the
/WEB-INF/hotels/booking directory.
transition
Use the transition element to handle events that occur within a state:
<view-state id="enterBookingDetails">
<transition on="submit" to="reviewBooking" />
</view-state>
These transitions drive view navigations.
end-state
Use the end-state element to define a flow outcome:
<end-state id="bookingCancelled" />
When a flow transitions to a end-state it terminates and the outcome is returned.
Example:
<flow xmlns="http://www.springframework.org/schema/webflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/webflow
http://www.springframework.org/schema/webflow/springwebflow-2.0.xsd">
<view-state id="enterBookingDetails">
<transition on="submit" to="reviewBooking" />
</view-state>
<view-state id="reviewBooking">
<transition on="confirm" to="bookingConfirmed" />
<transition on="revise" to="enterBookingDetails" />
<transition on="cancel" to="bookingCancelled" />
</view-state>
<end-state id="bookingConfirmed" />
<end-state id="bookingCancelled" />
</flow>
1.5) Actions
Most flows need to express more than just view navigation logic. Typically they also need to invoke business services of the application or other actions.
Within a flow, there are several points where you can execute actions. These points are:
• On flow start
• On state entry
• On view render
• On transition execution
• On state exit
• On flow end
Actions are defined using a concise expression language. Spring Web Flow uses the Unified EL by default. The next few sections will cover the essential language elements for defining actions.
evaluate :
The action element you will use most often is the evaluate element. Use the evaluate element to evaluate an expression at a point within your flow. With this single tag you can invoke methods on Spring beans or any other flow variable. For example:
<evaluate expression="entityManager.persist(booking)" />
Assigning an evaluate result :
If the expression returns a value, that value can be saved in the flow's data model called flowScope:
<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels"/>
Converting an evaluate result :
If the expression returns a value that may need to be converted, specify the desired type using the result-type attribute:
<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" result-type="dataModel"/>
1.6) Input/Output Mapping
Each flow has a well-defined input/output contract. Flows can be passed input attributes when they start, and can return output attributes when they end.
<input name="hotelId" type="long" value="flowScope.hotelId" required="true" />
Make it input Name , type , corresponding value and is mandatory field.
<end-state id="bookingConfirmed">
<output name="bookingId" />
</end-state>
1.7) Variables
A flow may declare one or more instance variables. These variables are allocated when the flow starts. Any @Autowired transient references the variable holds are also rewired when the flow resumes.
var : Use the var element to declare a flow variable:
<var name="searchCriteria" lass="com.mycompany.myapp.hotels.search.SearchCriteria"/>
Make sure your variable's class implements java.io.Serializable, as the instance state is saved between flow requests.
Variable Scopes:
Web Flow can store variables in one of several scopes:
Flow Scope:
Flow scope gets allocated when a flow starts and destroyed when the flow ends. With the default implementation, any objects stored in flow scope need to be Serializable.
View Scope:
View scope gets allocated when a view-state enters and destroyed when the state exits. View scope is only referenceable from within a view-state. With the default implementation, any objects stored in view scope need to be Serializable.
Request Scope :
Request scope gets allocated when a flow is called and destroyed when the flow returns.
Flash Scope :
Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends.
With the default implementation, any objects stored in flash scope need to be Serializable.
Conversation Scope :
Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends.
Conversation scope is shared by a top-level flow and all of its sub flows. With the default implementation,
conversation scoped objects are stored in the HTTP session and should generally be Serializable to account
for typical session replication.
1.8) Calling Subflows :
A flow may call another flow as a subflow. The flow will wait until the subflow returns, then respond to the subflow outcome.
subflow-state
Use the subflow-state element to call another flow as a subflow:
<subflow-state id="addGuest" subflow="createGuest">
<transition on="guestCreated" to="reviewBooking">
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
</transition>
<transition on="creationCancelled" to="reviewBooking" />
</subflow-state>
Passing a subflow input : Use the input element to pass input to the subflow:
<subflow-state id="addGuest" subflow="createGuest">
<input name="booking" />
<transition to="reviewBooking" />
</subflow-state>
Mapping subflow output : Simply refer to a subflow output attribute by its name within a outcome transition:
<transition on="guestCreated" to="reviewBooking">
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
</transition>
Final Example :
<flow xmlns="http://www.springframework.org/schema/webflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/webflow
http://www.springframework.org/schema/webflow/springwebflow-
2.0.xsd">
<input name="hotelId" />
<on-start>
<evaluate expression="bookingService.createBooking(hotelId, currentUser.name)" result="flowScope.booking" />
</on-start>
<view-state id="enterBookingDetails">
<transition on="submit" to="reviewBooking" />
</view-state>
<view-state id="reviewBooking">
<transition on="addGuest" to="addGuest" />
<transition on="confirm" to="bookingConfirmed" />
<transition on="revise" to="enterBookingDetails" />
<transition on="cancel" to="bookingCancelled" />
</view-state>
<subflow-state id="addGuest" subflow="createGuest">
<transition on="guestCreated" to="reviewBooking">
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
</transition>
<transition on="creationCancelled" to="reviewBooking" />
</subflow-state>
<end-state id="bookingConfirmed" >
<output name="bookingId" value="booking.id" />
</end-state>
<end-state id="bookingCancelled" />
</flow>
2) Expression Language (EL) :
EL is used for many things within a flow including:
1. Access client data such as declaring flow inputs or referencing request parameters.
2. Access data in Web Flow's RequestContext such as flowScope or currentEvent.
3. Invoke methods on Spring-managed objects through actions.
4. Resolve expressions such as state transition criteria, subflow ids, and view names.
2.1) Expression types :
Standard Expressions: The first and most common type of expression is the standard expression. Such expressions are evaluated directly by the EL and need not be enclosed in delimiters like #{}. Ex : <evaluate expression="searchCriteria.nextPage()" />
Template expressions : The second type of expression is a template expression. A template expression allows mixing of literal text with one or more standard expressions. Each standard expression block is explicitly surrounded with the #{} delimiters.
For example: <view-state id="error" view="error-#{externalContext.locale}.xhtml" />
List of implicit variables:
1) flowScope : Use flowScope to assign a flow variable. Flow scope gets allocated when a flow starts and destroyed when the flow ends. With the default implementation, any objects stored in flow scope need to be Serializable.
<evaluate expression="searchService.findHotel(hotelId)" result="flowScope.hotel" />
2) viewScope : Use viewScope to assign a view variable. View scope gets allocated when a view-state enters and destroyed when the state exits. View scope is only referenceable from within a view-state. With the default implementation, any objects stored in view scope need to be Serializable.
<on-render>
<evaluate expression="searchService.findHotels(searchCriteria)" result="viewScope.hotels"
result-type="dataModel" />
</on-render>
3) requestScope : Use requestScope to assign a request variable. Request scope gets allocated when a flow is called and destroyed when the flow returns.
<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
4) flashScope : Use flashScope to assign a flash variable. Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends. With the default implementation, any objects stored in flash scope need to be Serializable.
<set name="flashScope.statusMessage" value="'Booking confirmed'" />
5) conversationScope : Use conversationScope to assign a conversation variable. Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends. Conversation scope is shared by a top-level flow and all of its subflows. With the default implementation, conversation scoped objects are stored in the HTTP session and should generally be Serializable to account for typical session replication.
<evaluate expression="searchService.findHotel(hotelId)" result="conversationScope.hotel" />
6) requestParameters: Use requestParameters to access a client request parameter:
<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
7) currentEvent : Use currentEvent to access attributes of the current Event:
<evaluate expression="booking.guests.add(currentEvent.attributes.guest)" />
8) currentUser: Use currentUser to access the authenticated Principal:
<evaluate expression="bookingService.createBooking(hotelId, currentUser.name)"
result="flowScope.booking" />
9) messageContext : Use messageContext to access a context for retrieving and creating flow execution messages, including error and success messages. See the MessageContext Javadocs for more information.
<evaluate expression="bookingValidator.validate(booking, messageContext)" />
10) resourceBundle : Use resourceBundle to access a message resource.
<set name="flashScope.successMessage" value="resourceBundle.successMessage" />
11) flowRequestContext : Use flowRequestContext to access the RequestContext API, which is a representation of the current flow request. See the API Javadocs for more information.
12) flowExecutionContext : Use flowExecutionContext to access the FlowExecutionContext API, which is a representation of the current flow state. See the API Javadocs for more information.
13) flowExecutionUrl : Use flowExecutionUrl to access the context-relative URI for the current flow execution view-state.
14) externalContext :Use externalContext to access the client environment, including user session attributes.
<evaluate expression="searchService.suggestHotels(externalContext.sessionMap.userProfile)"
result="viewScope.hotels" />
No comments:
Post a Comment