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

SWF-1237 Documentation updates for 2.1 release

Browse Source
This commit is contained in:
Rossen Stoyanchev
2010-06-03 15:15:37 +00:00
parent f9f9fd094b
commit 518dfc2ccf
9 changed files with 413 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
spring-binding/src/main/java/org/springframework/binding/convert/service/GenericConversionService.java
View File

@@ -133,7 +133,8 @@ public class GenericConversionService implements ConversionService {
* @param id the id of the custom converter instance
* @param converter the converter
*
* @deprecated use {@link #addConverter(Converter)} instead
* @deprecated use {@link #addConverter(Converter)} instead or better yet use Spring 3 type conversion and
* formatting options (see Spring Documentation).
*/
public void addConverter(String id, Converter converter) {
customConverters.put(id, converter);

203
spring-webflow-reference/src/el.xml
View File

@@ -4,66 +4,32 @@
<sect1 id="el-introduction">
<title>Introduction</title>
<para>
Web Flow uses EL to access its data model and invoke actions.
This chapter will familiarize you with the EL syntax, and special EL variables you can reference from your flow definition.
Web Flow uses EL to access its data model and to invoke actions.
This chapter will familiarize you with EL syntax, configuration, and special EL variables you can reference from your flow definition.
</para>
</sect1>
<sect1 id="el-language-choices">
<title>Supported EL implementations</title>
<sect2 id="el-unified-el">
<title>Unified EL</title>
<para>
Web Flow attempts to use the <ulink url="http://en.wikipedia.org/wiki/Unified_Expression_Language">Unified EL</ulink> by default.
<code>jboss-el</code> is currently the default EL implementation.
When found in your classpath along with the <code>el-api</code>, it will be used automatically.
You can find the JBoss EL jar in the <ulink url="http://www.springsource.com/repository/app/bundle/detail?name=com.springsource.org.jboss.el">SpringSource Bundle Repository</ulink>.
<note>
The <code>el-api</code> dependency is typically <emphasis>provided</emphasis> by your web container. Tomcat 6 includes it, for example.
</note>
</para>
</sect2>
<sect2 id="el-ognl">
<title>OGNL</title>
<para>
<ulink url="http://www.ognl.org">OGNL</ulink> is the other EL supported by Web Flow 2.
OGNL is the EL most familiar to Web Flow version 1.0 users.
To use ognl, simply include <code>ognl</code> in your classpath instead of <code>jboss-el</code>.
Please refer to the <ulink url="http://www.ognl.org/2.6.9/Documentation/html/LanguageGuide/index.html">OGNL language guide</ulink> for specifics on its EL syntax.
</para>
</sect2>
</sect1>
<sect1 id="el-portability">
<title>EL portability</title>
<para>
In general, you will find the Unified EL and OGNL have a very similar syntax.
For basic variable resolution, property access, and method invocation the syntax is identical.
We recommend adhering to Unified EL syntax whenever possible, and only relying on proprietary EL features when needed.
</para>
</sect1>
<sect1 id="el-usage">
<title>EL usage</title>
<para>
EL is used for many things within a flow, including:
EL is used for many things within a flow including:
</para>
<orderedlist>
<listitem><para>Accessing data provided by the client, such as flow input attributes and request parameters.</para></listitem>
<listitem><para>Accessing internal data structures such as <code>flowScope.</code></para></listitem>
<listitem><para>Invoking methods on Spring beans.</para></listitem>
<listitem><para>Resolving constructs such as state transition criteria, subflow ids, and view names.</para></listitem>
</orderedlist>
<para>
Views rendered by flows typically access flow data structures using EL as well.
</para>
<listitem><para>Access client data such as declaring flow inputs or referencing request parameters.</para></listitem>
<listitem><para>Access data in Web Flow's <code>RequestContext</code> such as <code>flowScope</code> or <code>currentEvent</code>.</para></listitem>
<listitem><para>Invoke methods on Spring-managed objects through actions.</para></listitem>
<listitem><para>Resolve expressions such as state transition criteria, subflow ids, and view names.</para></listitem>
</orderedlist>
<para>
EL is also used to bind form parameters to model objects and reversely to render formatted form fields from the properties of a model object.
That however does not apply when using Web Flow with JSF in which case the standard JSF component lifecyle applies.
</para>
<sect2 id="el-types">
<title>Expression types</title>
<para>
There are basically two types of expressions in Web Flow.
An important concept to understand is there are two types of expressions in Web Flow: standard expressions and template expressions.
</para>
<sect3 id="el-types-eval">
<title>Standard eval expressions</title>
<title>Standard Expressions</title>
<para>
The first, and most common, type of expression, is the standard <emphasis>eval expression</emphasis>.
Such expressions are dynamically evaluated by the EL and should not be enclosed in delimiters like <code>${}</code> or <code>#{}</code>.
The first and most common type of expression is the <emphasis>standard expression</emphasis>.
Such expressions are evaluated directly by the EL and need not be enclosed in delimiters like <code>#{}</code>.
For example:
</para>
<programlisting language="xml"><![CDATA[
@@ -71,33 +37,105 @@
</programlisting>
<para>
The expression above is a standard expression that invokes the <code>nextPage</code> method on the <code>searchCriteria</code> variable when evaluated.
Attempting to enclose this expression in special eval delimiters like <code>${}</code> or <code>#{}</code> will result in an <code>IllegalArgumentException</code>.
<note>
We view use of special eval delimiters as redundant in this context, as the only acceptable value for the <code>expression</code> attribute is a single eval expression string.
</note>
If you attempt to enclose this expression in a special delimiter like <code>#{}</code> you will get an <code>IllegalArgumentException</code>.
In this context the delimiter is seen as redundant.
The only acceptable value for the <code>expression</code> attribute is an single expression string.
</para>
</sect3>
<sect3 id="el-types-template">
<title>Template expressions</title>
<para>
The second type of expression is a "template" expression.
Such expressions allow a mixing of literal text with one or more eval blocks.
Each eval block is explictly delimited with the <code>${}</code> delimiters.
The second type of expression is a <emphasis>template expression</emphasis>.
A template expression allows mixing of literal text with one or more standard expressions.
Each standard expression block is explicitly surrounded with the <code>#{}</code> delimiters.
For example:
</para>
<programlisting language="xml"><![CDATA[
<view-state id="error" view="error-${externalContext.locale}.xhtml" />]]>
<view-state id="error" view="error-#{externalContext.locale}.xhtml" />]]>
</programlisting>
<para>
The expression above is a template expression.
The result of evaluation will be a string that concatenates the literal text <code>error-</code> with the result of evaluating <code>externalContext.locale</code>.
As you can see, explicit delimiters are necessary here to demarcate eval blocks within the template.
The result of evaluation will be a string that concatenates literal text such as <code>error-</code> and <code>.xhtml</code> with the result of evaluating <code>externalContext.locale</code>.
As you can see, explicit delimiters are necessary here to demarcate standard expression blocks within the template.
</para>
<note>
See the Web Flow XML schema for a complete listing of those XML attributes that accept standard expressions and those that accept template expressions.
You can also use F2 in Eclipse (or equivalent shortcut in other IDEs) to access available documentation when typing out specific flow definition attributes.
</note>
</sect3>
</sect2>
</sect1>
<sect1 id="el-language-choices">
<title>EL Implementations</title>
<sect2 id="el-spring-el">
<title>Spring EL</title>
<para>
See the Web Flow XML schema for a complete listing of the XML attributes that accept standard expressions and template expressions.
Starting with version 2.1 Web Flow uses the <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html">Spring Expression Language</ulink> (Spring EL).
Spring EL was created to provide is a single, well-supported expression language for use across all the products in the Spring portfolio.
It is distributed as a separate jar <code>org.springframework.expression</code> in the Spring Framework.
Existing applications will need to remove dependencies on <code>org.jboss.el</code> or <code>org.ognl</code> and use <code>org.springframework.expression</code> instead.
See the section below on EL Portability for other notes on upgrading.
</para>
</sect2>
<sect2 id="el-unified-el">
<title>Unified EL</title>
<para>
In Web Flow 2.0 <ulink url="http://en.wikipedia.org/wiki/Unified_Expression_Language">Unified EL</ulink> was the default expression language with <code>jboss-el</code> as the implementation.
Use of Unified EL also implies a dependency on <code>el-api</code> although that is typically <emphasis>provided</emphasis> by your web container.
Tomcat 6 includes it, for example.
Spring EL is the default and recommended expression language to use.
However it is possible to replace it with Unified EL if you wish to do so.
You need the following Spring configuration to plug in the <code>WebFlowELExpressionParser</code> to the <code>flow-builder-services</code>:
<programlisting language="xml"><![CDATA[
<webflow:flow-builder-services expression-parser="expressionParser"/>
<bean id="expressionParser" class="org.springframework.webflow.expression.el.WebFlowELExpressionParser">
<constructor-arg>
<bean class="org.jboss.el.ExpressionFactoryImpl" />
</constructor-arg>
</bean>]]>
</programlisting>
</para>
</sect2>
<sect2 id="el-ognl">
<title>OGNL</title>
<para>
<ulink url="http://www.ognl.org">OGNL</ulink> is the third supported expression language.
OGNL is the EL most familiar to Web Flow version 1.0 users.
Please refer to the <ulink url="http://www.ognl.org/2.6.9/Documentation/html/LanguageGuide/index.html">OGNL language guide</ulink> for specifics on its EL syntax.
If you wish to use OGNL this is the Spring configuration necessary to plug it in:
<programlisting language="xml"><![CDATA[
<webflow:flow-builder-services expression-parser="expressionParser"/>
<bean id="expressionParser" class="org.springframework.webflow.expression.WebFlowOgnlExpressionParser"/>]]>
</programlisting>
</para>
</sect2>
</sect1>
<sect1 id="el-portability">
<title>EL portability</title>
<para>
In general, you will find Spring EL, Unified EL and OGNL to have a very similar syntax.
</para>
<para>
Note however there are some advantages to Spring EL.
For example Spring EL is closely integrated with the type conversion of Spring 3 and that allows you to take full advantage of its features.
Specifically the automatic detection of generic types as well as the use of formatting annotations is currently supported with Spring EL only.
</para>
<para>
There are some minor changes to keep in mind when upgrading to Spring EL from Unified EL or OGNL as follows:
<orderedlist>
<listitem><para>Expressions deliniated with <code>${}</code> in flow definitions must be changed to <code>#{}</code>.</para></listitem>
<listitem><para>Expressions testing the current event <code>#{currentEvent == 'submit'}</code> must be changed to <code>#{currentEvent.id == 'submit'}</code>.</para></listitem>
<listitem>
<para>
Resolving properties such as <code>#{currentUser.name}</code> may cause NullPointerException without any checks such as <code>#{currentUser != null ? currentUser.name : null}</code>.
A much better alternative though is the safe navigation operator <code>#{currentUser?.name}</code>.
</para>
</listitem>
</orderedlist>
For more information on Spring EL syntax please refer to the <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#expressions-language-ref">Language Reference</ulink> section in the Spring Documentation.
</para>
</sect1>
<sect1 id="el-variables">
<title>Special EL variables</title>
@@ -105,6 +143,45 @@
There are several implicit variables you may reference from within a flow.
These variables are discussed in this section.
</para>
<para>
Keep in mind this general rule.
Variables referring to data scopes (flowScope, viewScope, requestScope, etc.) should only be used when assigning a new variable to one of the scopes.
</para>
<para>
For example when assigning the result of the call to <code>bookingService.findHotels(searchCriteria)</code> to a new variable called "hotels" you must prefix it with a scope variable in order to let Web Flow know where you want it stored:
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<flow xmlns="http://www.springframework.org/schema/webflow" ... >
<var name="searchCriteria" class="org.springframework.webflow.samples.booking.SearchCriteria" />
<view-state id="reviewHotels">
<on-render>
<evaluate expression="bookingService.findHotels(searchCriteria)" result="viewScope.hotels" />
</on-render>
</view-state>
</flow>]]>
</programlisting>
However when setting an existing variable such as "searchCriteria" in the example below, you reference the variable directly without prefixing it with any scope variables:
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<flow xmlns="http://www.springframework.org/schema/webflow" ... >
<var name="searchCriteria" class="org.springframework.webflow.samples.booking.SearchCriteria" />
<view-state id="reviewHotels">
<transition on="sort">
<set name="searchCriteria.sortBy" value="requestParameters.sortBy" />
</transition>
</view-state>
</flow>]]>
</programlisting>
</para>
<para>
The following is the list of implicit variables you can reference within a flow definition:
</para>
<sect2 id="el-variable-flowScope">
<title>flowScope</title>
<para>
@@ -247,7 +324,7 @@
<sect1 id="el-scope-searching">
<title>Scope searching algorithm</title>
<para>
When assigning a variable in one of the flow scopes, referencing that scope is required.
As mentioned earlier in this section when assigning a variable in one of the flow scopes, referencing that scope is required.
For example:
</para>
<programlisting language="xml"><![CDATA[
@@ -261,7 +338,7 @@
<evaluate expression="entityManager.persist(booking)" />]]>
</programlisting>
<para>
If no scope is specified, like in the use of <code>booking</code> above, a scope searching algorithm will be employed.
When no scope is specified, like in the use of <code>booking</code> above, a scope searching algorithm is used.
The algorithm will look in request, flash, view, flow, and conversation scope for the variable.
If no such variable is found, an <code>EvaluationException</code> will be thrown.
</para>

4
spring-webflow-reference/src/overview.xml
View File

@@ -30,10 +30,10 @@
<sect1 id="system-requirements">
<title>What Web Flow requires to run</title>
<para>
Java 1.4 or higher
Java 1.5 or higher
</para>
<para>
Spring 2.5.6 or higher
Spring 3.0 or higher
</para>
</sect1>
<sect1 id="support">

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

@@ -4,59 +4,48 @@
<sect1 id="spring-faces-introduction">
<title>Introduction</title>
<para>
Spring Faces is Spring's JSF integration module that simplifies using JSF with Spring. It lets you use the
Spring Web Flow provides an integration that simplifies using JSF with Spring. It lets you use the
JSF UI Component Model with Spring MVC and Spring Web Flow controllers.
</para>
<para>
Spring Faces also includes a small Facelets component library that provides Ajax and client-side validation
capabilities. This component library builds on Spring Javascript, a Javascript abstraction framework that
integrates Dojo as the underlying UI toolkit.
A small Facelets component library that provides Ajax and client-side validation capabilities is also shipped with Web Flow.
</para>
</sect1>
<sect1 id="spring-faces-integration">
<title>Spring-centric Integration Approach</title>
<title>JSF Integration For Spring Developers</title>
<para>
Spring Faces combines the strengths of JSF, its UI component model, with the strengths of Spring, its
controller and configuration model. This brings you all the strengths of JSF without any of the weaknesses.
Spring Web Flow complements the strengths of JSF, its component model, and provides more sophisticated state management and navigation.
In addition you have the ability to use Spring MVC @Controller or flow definitions as controllers in the web layer.
</para>
<para>
Spring Faces provides a powerful supplement to a number of the standard JSF facilities, including:
JSF applications using Spring Web Flow applications gain benefits in the following areas:
<orderedlist>
<listitem>managed bean facility</listitem>
<listitem>scope management</listitem>
<listitem>event handling</listitem>
<listitem>navigation rules</listitem>
<listitem>easy modularization and packaging of views</listitem>
<listitem>cleaner URLs</listitem>
<listitem>model-level validation</listitem>
<listitem>client-side validation and UI enhancement</listitem>
<listitem>Ajax partial page updates and full navigation</listitem>
<listitem>progressive enhancement and graceful degradation</listitem>
<listitem>Managed bean facility</listitem>
<listitem>Scope management</listitem>
<listitem>Event handling</listitem>
<listitem>Navigation</listitem>
<listitem>Modularization and packaging of views</listitem>
<listitem>Cleaner URLs</listitem>
<listitem>Model-level validation</listitem>
<listitem>Progressivy-enhancement sytle client-side validation</listitem>
<listitem>Progressive-enhancement style Ajax requests with partial page updates</listitem>
</orderedlist>
Using these features will significantly reduce the amount of configuration required in faces-config.xml
while providing a cleaner separation between the view and controller layer and better modularization of your
application's functional responsibilities. These use of these features are outlined in the sections to
follow. As the majority of these features build on the flow definition language of Spring Web Flow, it is
assumed that you have an understanding of the foundations presented in
<link linkend="defining-flows">Defining Flows</link>
.
Using these features significantly reduce the amount of configuration required in faces-config.xml.
They provide a cleaner separation between the view and controller layers along with better modularization of application functionals.
These features are detailed in the sections to follow.
The majority of these features build on the flow definition language of Spring Web Flow.
Therefore it is assumed that you have an understanding of the foundations presented in <link linkend="defining-flows">Defining Flows</link>.
</para>
</sect1>
<sect1 id="spring-faces-config-web.xml">
<title>Configuring web.xml</title>
<para>
The first step to using Spring Faces is to route requests to the
<code>DispatcherServlet</code>
in the
<code>web.xml</code>
file. In this example, we map all URLs that begin with
<code>/spring/</code>
to the servlet. The servlet needs to be configured. An
<code>init-param</code>
is used in the servlet to pass the
<code>contextConfigLocation</code>
. This is the location of the Spring configuration for your application.
The first step is to route requests to the <code>DispatcherServlet</code> in the <code>web.xml</code> file.
In this example, we map all URLs that begin with <code>/spring/</code> to the servlet.
The servlet needs to be configured.
An <code>init-param</code> is used in the servlet to pass the <code>contextConfigLocation</code>.
This is the location of the Spring configuration for your web application.
</para>
<programlisting language="xml"><![CDATA[
<servlet>
@@ -79,8 +68,7 @@
<code>FacesServlet</code>
must be configured in
<code>web.xml</code>
as it normally would even though you generally will not need to route requests through it at all when using
Spring Faces.
as it normally would even though you generally will not need to route requests through it at all when using JSF with Spring Web Flow.
</para>
<programlisting language="xml"><![CDATA[
<!-- Just here so the JSF implementation can initialize, *not* used at runtime -->
@@ -97,9 +85,8 @@
</servlet-mapping>]]>
</programlisting>
<para>
When using the Spring Faces components, you also need to configure the Spring JavaScript
<code>ResourceServlet</code>
so that CSS and JavaScript resources may be output correctly by the components. This servlet must be mapped
When using the Spring Faces components, you also need to configure a servlet for serving
CSS and JavaScript resources. This servlet must be mapped
to /resources/* in order for the URL's rendered by the components to function correctly.
</para>
<programlisting language="xml"><![CDATA[
@@ -128,8 +115,8 @@
</context-param>]]>
</programlisting>
<para>
For optimal page-loading performance, the Spring Faces component library includes a few special components:
<code>includeStyles</code> and <code>includeScripts</code>. These components will eagerly load the neccessary
For optimal page-loading performance use the Spring Faces components
<code>includeStyles</code> and <code>includeScripts</code>. These components will eagerly load the necessary
CSS stylesheets and JavaScript files at the position they are placed in your JSF view template. In accordance
with the recommendations of the Yahoo Performance Guildlines, these two tags should be placed in the <code>head</code>
section of any page that uses the Spring Faces components. For example:
@@ -145,7 +132,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Spring Faces: Hotel Booking Sample Application</title>
<title>Hotel Booking Sample Application</title>
<sf:includeStyles />
<sf:includeScripts />
@@ -179,8 +166,8 @@
The next step is to configure Web Flow to render JSF views. To do this, in your Spring Web Flow
configuration include the
<code>faces</code>
namespace and link in the faces
<code>flow-builder-services</code>
namespace and link in the
<code>flow-builder-services</code> element from the faces custom namespace.
:
</para>
<programlisting language="xml"><![CDATA[
@@ -212,7 +199,6 @@
</programlisting>
<para>
The <code>faces:flow-builder-services</code> tag also configures several other defaults appropriate for a JSF environment.
Specifically, the Unified EL is configured as the default Expression Language.
</para>
<para>
See the swf-booking-faces reference application in the distribution for a complete working example.
@@ -221,11 +207,10 @@
<sect1 id="spring-faces-config">
<title>Configuring faces-config.xml</title>
<para>
The only configuration needed in
<code>faces-config.xml</code>
is specific to the use of Facelets. If you are using JSP and not using the Spring Faces components, you do
not need to add anything specific to Spring Faces to your
If using JSF 1.2 you need to provide the below configuration in
<code>faces-config.xml</code>
in order to use Facelets. If you are using JSP and not using the Spring Faces components, you do
not need to add anything to your <code>faces-config.xml</code>
</para>
<programlisting language="xml"><![CDATA[
<faces-config>
@@ -233,31 +218,51 @@
<!-- Enables Facelets -->
<view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
</application>
</faces-config>]]>
</programlisting>
<para>
If using JSF 2.0 then your faces-config.xml should use the faces-config schema version 2.0.
Also you should remove the FaceletViewHandler shown above if it is present as Facelets are now the default rendering technology in JSF 2.
</para>
<programlisting language="xml"><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
version="2.0">
<application></application>
</faces-config>]]>
</programlisting>
</sect1>
<sect1 id="spring-faces-managed-beans">
<title>Replacing the JSF Managed Bean Facility</title>
<para>
Spring Faces allows you to completely replace the JSF managed bean facility with a combination of
flow-managed variables and Spring managed beans. It gives you a good deal more control over the lifecycle of
When JSF with Spring Web Flow you can completely replace the JSF managed bean facility with a combination of
Web Flow managed variables and Spring managed beans. It gives you a good deal more control over the lifecycle of
your managed objects with well-defined hooks for initialization and execution of your domain model.
Additionally, since you are presumably already using Spring for your business layer, it reduces the
conceptual overhead of having to maintain two different managed bean models.
</para>
<para>
In doing pure JSF development, you will quickly find that request scope is not long-lived enough for storing
conversational model objects that drive complex event-driven views. The only available option is to begin
conversational model objects that drive complex event-driven views. In JSF 1.2 the only available option is to begin
putting things into session scope, with the extra burden of needing to clean the objects up before
progressing to another view or functional area of the application. What is really needed is a managed scope
that is somewhere between request and session scope. Fortunately web flow provides such extended facilities.
that is somewhere between request and session scope.
</para>
<para>
JSF 2 provides flash and view scopes that can be accessed programmatically via UIViewRoot.getViewMap().
Spring Web Flow provides access to flash, view, flow, and conversation scopes.
These scopes are seamlessly integrated through JSF variable resolvers and work the same in JSF 1.2 and in JSF 2.0 applications.
</para>
<sect2 id="spring-faces-flow-variables">
<title>Using Flow Variables</title>
<para>
The easiest and most natural way to declare and manage the model is through the use of
<link linkend="flow-variables">flow variables</link>
. You can declare these variables at the beginning of the flow:
<link linkend="flow-variables">flow variables</link>.
You can declare these variables at the beginning of the flow:
</para>
<programlisting language="xml"><![CDATA[
<var name="searchCriteria" class="com.mycompany.myapp.hotels.search.SearchCriteria"/>]]>
@@ -314,7 +319,7 @@
database) is quite common, but JSF by itself does not provide any convenient hooks for such
initialization. The flow definition language provides a natural facility for this through its
<link linkend="flow-actions">Actions</link>
. Spring Faces provides some extra conveniences for converting the outcome of an action into a
. Spring Web Flow provides some extra conveniences for converting the outcome of an action into a
JSF-specific data structure. For example:
</para>
<programlisting language="xml"><![CDATA[
@@ -477,7 +482,7 @@
<sect2 id="spring-faces-model-validation">
<title>Performing Model Validation</title>
<para>
JSF provides useful facilities for validating input at field-level before changes are applied to the
JSF 1.2 provides useful facilities for validating input at field-level before changes are applied to the
model, but when you need to then perform more complex validation at the model-level after the updates
have been applied, you are generally left with having to add more custom code to your JSF action methods
in the managed bean. Validation of this sort is something that is generally a responsibility of the
@@ -485,7 +490,7 @@
introducing an undesirable dependency on the JSF API in your domain layer.
</para>
<para>
With Spring Faces, you can utilize the generic and low-level
With Web Flow, you can utilize the generic and low-level
<code>MessageContext</code>
in your business code and any messages added there will then be available to the
<code>FacesContext</code>
@@ -518,21 +523,17 @@
<sect2 id="spring-faces-ajax-events">
<title>Handling Ajax Events</title>
<para>
Spring Faces provides some special
<code>UICommand</code>
components that go beyond the standard JSF components by adding the ability to do Ajax-based partial
The Spring Faces
<code>UICommand</code>
components have the ability to do Ajax-based partial
view updates. These components degrade gracefully so that the flow will still be fully functional by
falling back to full page refreshes if a user with a less capable browser views the page.
<note>
Though the core JSF support in Spring Faces is JSF 1.1-compatible, the Spring Faces
Ajax components require JSF 1.2.
</note>
</para>
<para>
Revisiting the earlier example with the paged table, you can change the "More Results" link to use an
Ajax request by replacing the standard
<code>commandButton</code>
with the Spring Faces version (note that the Spring Faces command components use Ajax by default, but
with the Spring Faces component version (note that the Spring Faces command components use Ajax by default, but
they can alternately be forced to use a normal form submit by setting ajaxEnabled="false" on the
component):
</para>
@@ -582,7 +583,7 @@
Faces tag library docs for full details.
</para>
<para>
An additional built-in feature when using the Spring Faces Ajax components is the ability to have the
An additional built-in feature when using the Spring Faces Ajax-enabled components is the ability to have the
response rendered inside a rich modal popup widget by setting
<code>popup="true"</code>
on a
@@ -613,7 +614,7 @@
<para>
JSF and Web Flow combine to provide an extensive server-side validation model for your web application, but
excessive roundtrips to the server to execute this validation and return error messages can be a tedious
experience for your users. Spring Faces provides a number of client-side rich validation controls that can
experience for your users. The Spring Faces component library provides a number of client-side rich validation controls that can
enhance the user experience by applying simple validations that give immediate feedback. Some simple
examples are illustrated below. See the Spring Faces taglib docs for a complete tag reference.
</para>
@@ -698,10 +699,10 @@
<sect1 id="spring-faces-component-libraries">
<title>Third-Party Component Library Integration</title>
<para>
Spring Faces strives to be compatible with any third-party JSF component library. By honoring all of the
The Spring Web Flow JSF integration strives to be compatible with any third-party JSF component library. By honoring all of the
standard semantics of the JSF specification within the SWF-driven JSF lifecycle, third-party libraries in
general should "just work". The main thing to remember is that configuration in web.xml will change slightly
since Spring Faces requests are not routed through the standard FacesServlet. Typically, anything that is
since Web Flow requests are not routed through the standard FacesServlet. Typically, anything that is
traditionally mapped to the FacesServlet should be mapped to the Spring DispatcherServlet instead. (You can
also map to both if for example you are migrating a legacy JSF application page-by-page.) In some cases, a
deeper level of integration can be achieved by configuring special flow services that are "aware" of a
@@ -710,8 +711,8 @@
<sect2 id="spring-faces-with-richfaces">
<title>Rich Faces Integration</title>
<para>
To use the Rich Faces component library with Spring Faces, the following filter configuration is needed
in web.xml (in addition to the typical Spring Faces configuration):
To use the Rich Faces component library with Spring Web Flow, the following filter configuration is needed
in web.xml (in addition to the other typical configuration already shown):
</para>
<programlisting language="xml"><![CDATA[
<filter>
@@ -791,19 +792,18 @@
<sect2 id="spring-faces-with-trinidad">
<title>Apache MyFaces Trinidad Integration</title>
<para>
The Apache MyFaces Trinidad library has been tested with the Spring Faces integration and proven to fit
The Apache MyFaces Trinidad library has been tested with the Spring Web Flow's JSF integration and proven to fit
in nicely. Deeper integration to allow the Trinidad components and Spring Faces components to play
well together has not yet been attempted, but Trinidad provides a pretty thorough solution on its own
when used in conjunction with the Spring Faces integration layer.
when used in conjunction with the Spring Web Flow JSF integration.
</para>
<para>
NOTE - An <code>AjaxHandler</code> implementation for Trinidad is not currently provided out-of-the-box with
Spring Faces. In order to fully integrate with Trinidad's PPR functionality, a custom implementation should be
NOTE: An <code>AjaxHandler</code> implementation for Trinidad is not currently provided out-of-the-box.
In order to fully integrate with Trinidad's PPR functionality, a custom implementation should be
provided. An community-provided partial example can be found here: <ulink url="http://jira.springsource.org/browse/SWF-1160">SWF-1160</ulink>
</para>
<para>
Typical Trinidad + Spring Faces configuration is as follows in web.xml (in addition to the typical
Spring Faces configuration):
Typical configuration when using Trinidad with Web Flow is as follows in web.xml (in addition what has already been shown):
</para>
<programlisting language="xml"><![CDATA[
<context-param>

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

@@ -3,6 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY overview SYSTEM "overview.xml">
<!ENTITY whatsnew SYSTEM "whatsnew.xml">
<!ENTITY defining-flows SYSTEM "defining-flows.xml">
<!ENTITY el SYSTEM "el.xml">
<!ENTITY views SYSTEM "views.xml">
@@ -63,6 +64,7 @@
<toc />
&overview;
&whatsnew;
&defining-flows;
&el;
&views;

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

@@ -197,8 +197,10 @@
<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.
Type conversion is used to convert from one type to another when required during flow execution such as when processing request parameters, invoking actions, and so on.
Many common object types such as numbers, classes, and enums are supported.
However you'll probably need to provide your own type conversion and formatting logic for custom data types.
Please read the <link linkend="view-type-conversion">Performing Type Conversion</link> section for important information on how to provide custom type conversion logic.
</para>
</sect3>
<sect3 id="builder-service-expression-parser">

11
spring-webflow-reference/src/upgrade-guide.xml
View File

@@ -82,7 +82,7 @@ java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml
<para>
EL expressions are used heavily throughout the flow definition language.
Many of the attributes that appear to be plain text are actually interpreted as EL.
The standard EL delimiters (either ${} or #{}) are not necessary and will often cause an exception if they are included.
The standard EL delimiters (either ${} or #{} in Web Flow 2.0 or just #{} in Web Flow 2.1) are not necessary and will often cause an exception if they are included.
</para>
<para>
EL delimiters should be removed where necessary by the updater tool.
@@ -234,11 +234,12 @@ java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml
</para>
</sect2>
<sect2 id="upgrade-guide-webflow-concepts-el-v-ognl">
<title>OGNL vs EL</title>
<title>OGNL vs Spring EL</title>
<para>
Web Flow 1 used OGNL exclusively for expressions within the flow definitions.
Web Flow 2 adds support for Unified EL.
United EL is used when it is available, OGNL will continue to be used when a Unified EL implementation is not available.
Web Flow 2.1 uses Spring EL by default.
United EL and OGNL can still be plugged in.
Please see the <link linkend="el">Expression Language</link> chapter for details.
</para>
</sect2>
@@ -252,9 +253,9 @@ java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml
</para>
</sect2>
<sect2 id="upgrade-guide-webflow-concepts-jsf">
<title>Spring Faces</title>
<title>JSF</title>
<para>
Web Flow 2 offers significantly improved integration with JavaServerFaces.
Web Flow 2 offers significantly improved integration with JSF.
Please see the <link linkend="spring-faces">JSF Integration</link> chapter for details.
</para>
</sect2>

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

@@ -169,67 +169,191 @@
<sect1 id="view-type-conversion">
<title>Performing type conversion</title>
<para>
When a model binding occurs during view postback, the binding system will attempt to convert the input value to the type of the target model property if necessary.
Default Converters are registered for common types such as Numbers, primitives, enums, and Dates and are applied automatically.
Users also have the ability to register their own converters for user-defined types, and to override the default Converters.
When request parameters are used to populate the model (commonly referred to as data binding), type conversion is required to parse String-based request parameter values before setting target model properties.
Default type conversion is available for many common Java types such as numbers, primitives, enums, and Dates.
Users also have the ability to register their own type conversion logic for user-defined types, and to override the default Converters.
</para>
<sect2 id="converter-impl">
<title>Implementing a Converter</title>
<sect2 id="converter-options">
<title>Type Conversion Options</title>
<para>
To implement your own Converter, implement the <code>org.springframework.binding.convert.converters.TwoWayConverter</code> interface.
A convenient <code>StringToObject</code> base class has been provided to simplify the implementation of this interface for converters
that convert from a user input String to a user-defined Object and back. Simply extend from this class and override these two methods:
</para>
<programlisting language="java">
protected abstract Object toObject(String string, Class targetClass) throws Exception;
protected abstract String toString(Object object) throws Exception;
</programlisting>
<para>
<code>toObject(String, Class)</code> should convert from the input string to your object's type, and <code>toString(Object)</code> should do the reverse.
</para>
<para>
The following example shows a Converter that converts from String to a MonetaryAmount for working with currency values:
</para>
<programlisting language="java">
public class StringToMonetaryAmount extends StringToObject {
public StringToMonetaryAmount() {
super(MonetaryAmount.class);
}
@Override
protected Object toObject(String string, Class targetClass) {
return MonetaryAmount.valueOf(string);
}
@Override
protected String toString(Object object) {
MonetaryAmount amount = (MonetaryAmount) object;
return amount.toString();
}
}
</programlisting>
<para>
Review the pre-built converters in the <code>org.springframework.binding.convert.converters</code> package to see more examples of Converter implementations.
Starting with version 2.1 Spring Web Flow uses the <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/validation.html#core-convert">type conversion</ulink> and <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/validation.html#format">formatting</ulink> system introduced in Spring 3 for nearly all type conversion needs.
Previously Web Flow applications used a type conversion mechanism that was different from the one in Spring MVC, which relied on the <code>java.beans.PropertyEditor</code> abstraction.
Spring 3 offers a modern type conversion alternative to PropertyEditors that was actually influenced by Web Flow's own type conversion system.
Hence Web Flow users should find it natural to work with the new Spring 3 type conversion.
Another obvious and very important benefit of this change is that a single type conversion mechanism can now be used across Spring MVC And Spring Web Flow.
</para>
</sect2>
<sect2 id="converter-registration">
<title>Registering a Converter</title>
<sect2 id="converter-upgrade-to-spring-3">
<title>Upgrading to Spring 3 Type Conversion And Formatting</title>
<para>
To install your own Converter or override any of the default Converters, extend from <code>org.springframework.binding.convert.service.DefaultConversionService</code> and override the <code>addDefaultConverters()</code> method.
Use the <code>addConverter(Converter)</code> method to register the primary Converter to use to convert between two types, such as a <code>String</code> and a <code>MonetaryAmount</code>.
Optionally use the <code>addConverter(String, Converter)</code> method to register alternate converters for the same type pair; for example, to support formatting a <code>java.util.Date</code> as a String in several different ways.
What does this practically mean for existing applications?
Existing applications are likely registering their own converters of type <code>org.springframework.binding.convert.converters.Converter</code> through a sub-class of <code>DefaultConversionService</code> available in Spring Binding.
Those converters can continue to be registered as before.
They will be adapted as Spring 3 <code>GenericConverter</code> types and registered with a Spring 3 <code>org.springframework.core.convert.ConversionService</code> instance.
In other words existing converters will be invoked through Spring's type conversion service.
</para>
<para>
Each alternate Converter is indexed by a unique <code>converterId</code> that can be referenced when configuring a model binding.
When no converter id is referenced explicitly by a binding, the primary Converter between the two types is always used.
The only exception to this rule are named converters, which can be referenced from a <code>binding</code> element in a <code>view-state</code>:
<programlisting language="java"><![CDATA[
public class ApplicationConversionService extends DefaultConversionService {
public ApplicationConversionService() {
addDefaultConverters();
addDefaultAliases();
addConverter("customConverter", new CustomConverter());
}
}]]>
</programlisting>
<programlisting language="xml"><![CDATA[
<view-state id="enterBookingDetails" model="booking">
<binder>
<binding property="checkinDate" required="true" converter="customConverter" />
</binder>
</view-state>]]>
</programlisting>
Named converters are not supported and cannot be used with the type conversion service available in Spring 3.
Therefore such converters will not be adapted and will continue to work as before, i.e. will not involve the Spring 3 type conversion.
However, this mechanism is deprecated and applications are encouraged to favor Spring 3 type conversion and formatting features.
</para>
<para>
Also note that the existing Spring Binding <code>DefaultConversionService</code> no longer registers any default converters.
Instead Web Flow now relies on the default type converters and formatters in Spring 3.
</para>
<para>
The ConversionService is the object Web Flow consults at runtime to lookup conversion executors to convert from one type to another.
There is generally one ConversionService per application.
See the <link linkend="builder-service-conversion">System Setup</link> section for documentation on how to configure an extended ConversionService implementation that registers custom Converters to apply application-wide.
Also consult the Convert API documentation for more information.
In summary the Spring 3 type conversion and formatting is now used almost exclusively in Web Flow.
Although existing applications will work without any changes, we encourage moving towards unifying the type conversion needs of Spring MVC and Spring Web Flow parts of applications.
</para>
</sect2>
<sect2 id="converter-configuration">
<title>Configuring Type Conversion and Formatting</title>
<para>
In Spring MVC an instance of a <code>FormattingConversionService</code> is created automatically through the custom MVC namespace:
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
<mvc:annotation-driven/>
]]>
</programlisting>
Internally that is done with the help of <code>FormattingConversionServiceFactoryBean</code>, which registers a default set of converters and formatters.
You can customize the conversion service instance used in Spring MVC through the <code>conversion-service</code> attribute:
<programlisting language="xml"><![CDATA[
<mvc:annotation-driven conversion-service="applicationConversionService" />]]>
</programlisting>
</para>
<para>
In Web Flow an instance of a Spring Binding <code>DefaultConversionService</code> is created automatically, which does not register any converters.
Instead it delegates to a <code>FormattingConversionService</code> instance for all type conversion needs.
By default this is not the same <code>FormattingConversionService</code> instance as the one used in Spring 3.
However that won't make a practical difference until you start registering your own formatters.
</para>
<para>
The <code>DefaultConversionService</code> used in Web Flow can be customized through the flow-builder-services element:
<programlisting language="xml"><![CDATA[
<webflow:flow-builder-services id="flowBuilderServices" conversion-service="defaultConversionService" />]]>
</programlisting>
</para>
<para>
Connecting the dots in order to register your own formatters for use in both Spring MVC and in Spring Web Flow you can do the following.
Create a class to register your custom formatters:
<programlisting language="java"><![CDATA[
public class ApplicationConversionServiceFactoryBean extends FormattingConversionServiceFactoryBean {
@Override
protected void installFormatters(FormatterRegistry registry) {
// ...
}
}
]]>
</programlisting>
Configure it for use in Spring MVC:
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
<mvc:annotation-driven conversion-service="applicationConversionService" />
<!--
Alternatively if you prefer annotations for DI:
1. Add @Component to the factory bean.
2. Add a component-scan element (from the context custom namespace) here.
3. Remove XML bean declaration below.
-->
<bean id="applicationConversionService" class="somepackage.ApplicationConversionServiceFactoryBean">
]]>
</programlisting>
Connection the Web Flow <code>DefaultConversionService</code> to the same "applicationConversionService" bean used in Spring MVC:
<programlisting language="xml"><![CDATA[
<webflow:flow-registry id="flowRegistry" flow-builder-services="flowBuilderServices" ... />
<webflow:flow-builder-services id="flowBuilderServices" conversion-service="defaultConversionService" ... />
<bean id="defaultConversionService" class="org.springframework.binding.convert.service.DefaultConversionService">
<constructor-arg ref="applicationConversionSevice"/>
</bean>]]>
</programlisting>
Of course it is also possible to mix and match.
Register new Spring 3 <code>Formatter</code> types through the "applicationConversionService".
Register existing Spring Binding <code>Converter</code> types through the "defaultConversionService".
</para>
</sect2>
<sect2 id="converter-working-with">
<title>Working With Spring 3 Type Conversion And Formatting</title>
<para>
An important concept to understand is the difference between type converters and formatters.
</para>
<para>
Type converters in Spring 3, provided in <code>org.springframework.core</code>, are for general-purpose type conversion between any two object types.
In addition to the most simple <code>Converter</code> type, two other interfaces are <code>ConverterFactory</code> and <code>GenericConverter</code>.
</para>
<para>
Formatters in Spring 3, provided in <code>org.springframework.context</code>, have the more specialized purpose of representing Objects as Strings.
The <code>Formatter</code> interface extends the <code>Printer</code> and <code>Parser</code> interfaces for converting an Object to a String and turning a String into an Object.
</para>
<para>
Web developers will find the <code>Formatter</code> interface most relevant because it fits the needs of web applications for type conversion.
<note>
An important point to be made is that Object-to-Object conversion is a generalization of the more specific Object-to-String conversion.
In fact in the end <code>Formatters</code> are reigstered as <code>GenericConverter</code> types with Spring's <code>GenericConversionService</code> making them equal to any other converter.
</note>
</para>
</sect2>
<sect2 id="converter-formatting-annotations">
<title>Formatting Annotations</title>
<para>
One of the best features of the new type conversion is the ability to use annotations for a better control over formatting in a concise manner.
Annotations can be placed on model attributes and on arguments of @Controller methods that are mapped to requests.
Out of the box Spring provides two annotations <code>NumberFormat</code> and <code>DateTimeFormat</code> but you can create your own and have them registered along with the associated formatting logic.
You can see examples of the <code>DateTimeFormat</code> annotation in the <ulink url="https://src.springframework.org/svn/spring-samples/travel">Spring Travel</ulink> and in the <ulink url="https://src.springframework.org/svn/spring-samples/petcare">Petcare</ulink> along with other samples in the <ulink url="https://src.springframework.org/svn/spring-samples">Spring Samples</ulink> repository.
</para>
</sect2>
<sect2 id="converter-dates">
<title>Working With Dates</title>
<para>
The <code>DateTimeFormat</code> annotation implies use of <ulink url="http://joda-time.sourceforge.net/">Joda Time</ulink>.
If that is present on the classpath the use of this annotation is enabled automatically.
By default neither Spring MVC nor Web Flow register any other date formatters or converters.
Therefore it is important for applications to register a custom formatter to specify the default way for printing and parsing dates.
The <code>DateTimeFormat</code> annotation on the other hand provides more fine-grained control where it is necessary to deviate from the default.
</para>
<para>
For more information on working with Spring 3 type conversion and formatting please refer to the relevant sections of the <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/index.html">Spring documentation</ulink>.
</para>
</sect2>
</sect1>

2
spring-webflow-samples/booking-faces/src/main/webapp/WEB-INF/flows/main/main-flow.xml
View File

@@ -7,7 +7,7 @@
<view-state id="enterSearchCriteria">
<on-render>
<evaluate expression="bookingService.findBookings(currentUser!=null?currentUser.name:null)" result="viewScope.bookings" result-type="dataModel" />
<evaluate expression="bookingService.findBookings(currentUser?.name)" result="viewScope.bookings" result-type="dataModel" />
</on-render>
<transition on="search" to="reviewHotels">
<evaluate expression="searchCriteria.resetPage()" />