diff --git a/spring-binding/src/main/java/org/springframework/binding/convert/service/GenericConversionService.java b/spring-binding/src/main/java/org/springframework/binding/convert/service/GenericConversionService.java index 9221b054..d9253050 100644 --- a/spring-binding/src/main/java/org/springframework/binding/convert/service/GenericConversionService.java +++ b/spring-binding/src/main/java/org/springframework/binding/convert/service/GenericConversionService.java @@ -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); diff --git a/spring-webflow-reference/src/el.xml b/spring-webflow-reference/src/el.xml index 58cf856a..aac5e166 100644 --- a/spring-webflow-reference/src/el.xml +++ b/spring-webflow-reference/src/el.xml @@ -4,66 +4,32 @@ Introduction - 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. - - - Supported EL implementations - - Unified EL - - Web Flow attempts to use the Unified EL by default. - jboss-el is currently the default EL implementation. - When found in your classpath along with the el-api, it will be used automatically. - You can find the JBoss EL jar in the SpringSource Bundle Repository. - - The el-api dependency is typically provided by your web container. Tomcat 6 includes it, for example. - - - - - OGNL - - OGNL 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 ognl in your classpath instead of jboss-el. - Please refer to the OGNL language guide for specifics on its EL syntax. - - - - - EL portability - 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. - - - - EL usage - - EL is used for many things within a flow, including: + EL is used for many things within a flow including: - Accessing data provided by the client, such as flow input attributes and request parameters. - Accessing internal data structures such as flowScope. - Invoking methods on Spring beans. - Resolving constructs such as state transition criteria, subflow ids, and view names. - - - Views rendered by flows typically access flow data structures using EL as well. - + Access client data such as declaring flow inputs or referencing request parameters. + Access data in Web Flow's RequestContext such as flowScope or currentEvent. + Invoke methods on Spring-managed objects through actions. + Resolve expressions such as state transition criteria, subflow ids, and view names. + + + 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. + Expression types - 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. - Standard eval expressions + Standard Expressions - The first, and most common, type of expression, is the standard eval expression. - Such expressions are dynamically evaluated by the EL and should not be enclosed in delimiters like ${} or #{}. + 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 #{}. For example: The expression above is a standard expression that invokes the nextPage method on the searchCriteria variable when evaluated. - Attempting to enclose this expression in special eval delimiters like ${} or #{} will result in an IllegalArgumentException. - - We view use of special eval delimiters as redundant in this context, as the only acceptable value for the expression attribute is a single eval expression string. - + If you attempt to enclose this expression in a special delimiter like #{} you will get an IllegalArgumentException. + In this context the delimiter is seen as redundant. + The only acceptable value for the expression attribute is an single expression string. Template expressions - 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 ${} delimiters. + 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: ]]> +]]> The expression above is a template expression. - The result of evaluation will be a string that concatenates the literal text error- with the result of evaluating externalContext.locale. - 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 error- and .xhtml with the result of evaluating externalContext.locale. + As you can see, explicit delimiters are necessary here to demarcate standard expression blocks within the template. + + 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. + + + + + EL Implementations + + Spring EL - 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 Spring Expression Language (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 org.springframework.expression in the Spring Framework. + Existing applications will need to remove dependencies on org.jboss.el or org.ognl and use org.springframework.expression instead. + See the section below on EL Portability for other notes on upgrading. + + Unified EL + + In Web Flow 2.0 Unified EL was the default expression language with jboss-el as the implementation. + Use of Unified EL also implies a dependency on el-api although that is typically provided 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 WebFlowELExpressionParser to the flow-builder-services: + + + + + + +]]> + + + + + OGNL + + OGNL is the third supported expression language. + OGNL is the EL most familiar to Web Flow version 1.0 users. + Please refer to the OGNL language guide for specifics on its EL syntax. + If you wish to use OGNL this is the Spring configuration necessary to plug it in: + + +]]> + + + + + + EL portability + + In general, you will find Spring EL, Unified EL and OGNL to have a very similar syntax. + + + 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. + + + There are some minor changes to keep in mind when upgrading to Spring EL from Unified EL or OGNL as follows: + + Expressions deliniated with ${} in flow definitions must be changed to #{}. + Expressions testing the current event #{currentEvent == 'submit'} must be changed to #{currentEvent.id == 'submit'}. + + + Resolving properties such as #{currentUser.name} may cause NullPointerException without any checks such as #{currentUser != null ? currentUser.name : null}. + A much better alternative though is the safe navigation operator #{currentUser?.name}. + + + + For more information on Spring EL syntax please refer to the Language Reference section in the Spring Documentation. + Special EL variables @@ -105,6 +143,45 @@ There are several implicit variables you may reference from within a flow. These variables are discussed in this section. + + 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. + + + For example when assigning the result of the call to bookingService.findHotels(searchCriteria) 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: + + + + + + + + + + + +]]> + + 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: + + + + + + + + + + + +]]> + + + + The following is the list of implicit variables you can reference within a flow definition: + flowScope @@ -247,7 +324,7 @@ Scope searching algorithm - 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: ]]> - If no scope is specified, like in the use of booking above, a scope searching algorithm will be employed. + When no scope is specified, like in the use of booking 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 EvaluationException will be thrown. diff --git a/spring-webflow-reference/src/overview.xml b/spring-webflow-reference/src/overview.xml index 8fcc6ee4..fb6f0bb4 100644 --- a/spring-webflow-reference/src/overview.xml +++ b/spring-webflow-reference/src/overview.xml @@ -30,10 +30,10 @@ What Web Flow requires to run - Java 1.4 or higher + Java 1.5 or higher - Spring 2.5.6 or higher + Spring 3.0 or higher diff --git a/spring-webflow-reference/src/spring-faces.xml b/spring-webflow-reference/src/spring-faces.xml index 1490a394..298a0a0c 100644 --- a/spring-webflow-reference/src/spring-faces.xml +++ b/spring-webflow-reference/src/spring-faces.xml @@ -4,59 +4,48 @@ Introduction - 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. - 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. - Spring-centric Integration Approach + JSF Integration For Spring Developers - 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. - 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: - managed bean facility - scope management - event handling - navigation rules - easy modularization and packaging of views - cleaner URLs - model-level validation - client-side validation and UI enhancement - Ajax partial page updates and full navigation - progressive enhancement and graceful degradation + Managed bean facility + Scope management + Event handling + Navigation + Modularization and packaging of views + Cleaner URLs + Model-level validation + Progressivy-enhancement sytle client-side validation + Progressive-enhancement style Ajax requests with partial page updates - 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 - Defining Flows - . + 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 Defining Flows. Configuring web.xml - The first step to using Spring Faces is to route requests to the - DispatcherServlet - in the - web.xml - file. In this example, we map all URLs that begin with - /spring/ - to the servlet. The servlet needs to be configured. An - init-param - is used in the servlet to pass the - contextConfigLocation - . This is the location of the Spring configuration for your application. + The first step is to route requests to the DispatcherServlet in the web.xml file. + In this example, we map all URLs that begin with /spring/ to the servlet. + The servlet needs to be configured. + An init-param is used in the servlet to pass the contextConfigLocation. + This is the location of the Spring configuration for your web application. @@ -79,8 +68,7 @@ FacesServlet must be configured in web.xml - 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. @@ -97,9 +85,8 @@ ]]> - When using the Spring Faces components, you also need to configure the Spring JavaScript - ResourceServlet - 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. ]]> - For optimal page-loading performance, the Spring Faces component library includes a few special components: - includeStyles and includeScripts. These components will eagerly load the neccessary + For optimal page-loading performance use the Spring Faces components + includeStyles and includeScripts. 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 head section of any page that uses the Spring Faces components. For example: @@ -145,7 +132,7 @@ - Spring Faces: Hotel Booking Sample Application + Hotel Booking Sample Application @@ -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 faces - namespace and link in the faces - flow-builder-services + namespace and link in the + flow-builder-services element from the faces custom namespace. : The faces:flow-builder-services tag also configures several other defaults appropriate for a JSF environment. - Specifically, the Unified EL is configured as the default Expression Language. See the swf-booking-faces reference application in the distribution for a complete working example. @@ -221,11 +207,10 @@ Configuring faces-config.xml - The only configuration needed in - faces-config.xml - 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 faces-config.xml + 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 faces-config.xml @@ -233,31 +218,51 @@ com.sun.facelets.FaceletViewHandler +]]> + + + 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. + + + + + + ]]> Replacing the JSF Managed Bean Facility - 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. 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. + + + 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. Using Flow Variables The easiest and most natural way to declare and manage the model is through the use of - flow variables - . You can declare these variables at the beginning of the flow: + flow variables. + You can declare these variables at the beginning of the flow: ]]> @@ -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 Actions - . 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: Performing Model Validation - 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. - With Spring Faces, you can utilize the generic and low-level + With Web Flow, you can utilize the generic and low-level MessageContext in your business code and any messages added there will then be available to the FacesContext @@ -518,21 +523,17 @@ Handling Ajax Events - Spring Faces provides some special - UICommand - components that go beyond the standard JSF components by adding the ability to do Ajax-based partial + The Spring Faces + UICommand + 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. - - Though the core JSF support in Spring Faces is JSF 1.1-compatible, the Spring Faces - Ajax components require JSF 1.2. - Revisiting the earlier example with the paged table, you can change the "More Results" link to use an Ajax request by replacing the standard commandButton - 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): @@ -582,7 +583,7 @@ Faces tag library docs for full details. - 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 popup="true" on a @@ -613,7 +614,7 @@ 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. @@ -698,10 +699,10 @@ Third-Party Component Library Integration - 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 @@ Rich Faces Integration - 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): @@ -791,19 +792,18 @@ Apache MyFaces Trinidad Integration - 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. - NOTE - An AjaxHandler 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 AjaxHandler 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: SWF-1160 - 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): diff --git a/spring-webflow-reference/src/spring-webflow-reference.xml b/spring-webflow-reference/src/spring-webflow-reference.xml index a32cf6f3..ec72d4e5 100644 --- a/spring-webflow-reference/src/spring-webflow-reference.xml +++ b/spring-webflow-reference/src/spring-webflow-reference.xml @@ -3,6 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + @@ -63,6 +64,7 @@ &overview; + &whatsnew; &defining-flows; ⪙ &views; diff --git a/spring-webflow-reference/src/system-setup.xml b/spring-webflow-reference/src/system-setup.xml index 9a2cc999..73df2067 100644 --- a/spring-webflow-reference/src/system-setup.xml +++ b/spring-webflow-reference/src/system-setup.xml @@ -197,8 +197,10 @@ conversion-service Use the conversion-service attribute to customize the ConversionService 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 Performing Type Conversion section for important information on how to provide custom type conversion logic. diff --git a/spring-webflow-reference/src/upgrade-guide.xml b/spring-webflow-reference/src/upgrade-guide.xml index dfa42f58..e5e3586e 100644 --- a/spring-webflow-reference/src/upgrade-guide.xml +++ b/spring-webflow-reference/src/upgrade-guide.xml @@ -82,7 +82,7 @@ java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml 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. 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 - OGNL vs EL + OGNL vs Spring EL 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 Expression Language chapter for details. @@ -252,9 +253,9 @@ java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml - Spring Faces + JSF - Web Flow 2 offers significantly improved integration with JavaServerFaces. + Web Flow 2 offers significantly improved integration with JSF. Please see the JSF Integration chapter for details. diff --git a/spring-webflow-reference/src/views.xml b/spring-webflow-reference/src/views.xml index 49fdd32b..ccdbcb13 100644 --- a/spring-webflow-reference/src/views.xml +++ b/spring-webflow-reference/src/views.xml @@ -169,67 +169,191 @@ Performing type conversion - 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. - - Implementing a Converter + + Type Conversion Options - To implement your own Converter, implement the org.springframework.binding.convert.converters.TwoWayConverter interface. - A convenient StringToObject 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: - - -protected abstract Object toObject(String string, Class targetClass) throws Exception; - -protected abstract String toString(Object object) throws Exception; - - - toObject(String, Class) should convert from the input string to your object's type, and toString(Object) should do the reverse. - - - The following example shows a Converter that converts from String to a MonetaryAmount for working with currency values: - - -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(); - } -} - - - Review the pre-built converters in the org.springframework.binding.convert.converters package to see more examples of Converter implementations. + Starting with version 2.1 Spring Web Flow uses the type conversion and formatting 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 java.beans.PropertyEditor 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. - - Registering a Converter + + Upgrading to Spring 3 Type Conversion And Formatting - To install your own Converter or override any of the default Converters, extend from org.springframework.binding.convert.service.DefaultConversionService and override the addDefaultConverters() method. - Use the addConverter(Converter) method to register the primary Converter to use to convert between two types, such as a String and a MonetaryAmount. - Optionally use the addConverter(String, Converter) method to register alternate converters for the same type pair; for example, to support formatting a java.util.Date 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 org.springframework.binding.convert.converters.Converter through a sub-class of DefaultConversionService available in Spring Binding. + Those converters can continue to be registered as before. + They will be adapted as Spring 3 GenericConverter types and registered with a Spring 3 org.springframework.core.convert.ConversionService instance. + In other words existing converters will be invoked through Spring's type conversion service. - Each alternate Converter is indexed by a unique converterId 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 binding element in a view-state: + + + + + + +]]> + + 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. + + + Also note that the existing Spring Binding DefaultConversionService no longer registers any default converters. + Instead Web Flow now relies on the default type converters and formatters in Spring 3. - 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 System Setup 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. + + + + Configuring Type Conversion and Formatting + + In Spring MVC an instance of a FormattingConversionService is created automatically through the custom MVC namespace: + + + + +]]> + + Internally that is done with the help of FormattingConversionServiceFactoryBean, which registers a default set of converters and formatters. + You can customize the conversion service instance used in Spring MVC through the conversion-service attribute: + ]]> + + + + In Web Flow an instance of a Spring Binding DefaultConversionService is created automatically, which does not register any converters. + Instead it delegates to a FormattingConversionService instance for all type conversion needs. + By default this is not the same FormattingConversionService instance as the one used in Spring 3. + However that won't make a practical difference until you start registering your own formatters. + + + The DefaultConversionService used in Web Flow can be customized through the flow-builder-services element: + ]]> + + + + 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: + + + Configure it for use in Spring MVC: + + + + + + + + + +]]> + + Connection the Web Flow DefaultConversionService to the same "applicationConversionService" bean used in Spring MVC: + + + + + + + ]]> + + Of course it is also possible to mix and match. + Register new Spring 3 Formatter types through the "applicationConversionService". + Register existing Spring Binding Converter types through the "defaultConversionService". + + + + Working With Spring 3 Type Conversion And Formatting + + An important concept to understand is the difference between type converters and formatters. + + + Type converters in Spring 3, provided in org.springframework.core, are for general-purpose type conversion between any two object types. + In addition to the most simple Converter type, two other interfaces are ConverterFactory and GenericConverter. + + + Formatters in Spring 3, provided in org.springframework.context, have the more specialized purpose of representing Objects as Strings. + The Formatter interface extends the Printer and Parser interfaces for converting an Object to a String and turning a String into an Object. + + + Web developers will find the Formatter interface most relevant because it fits the needs of web applications for type conversion. + + 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 Formatters are reigstered as GenericConverter types with Spring's GenericConversionService making them equal to any other converter. + + + + + Formatting Annotations + + 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 NumberFormat and DateTimeFormat but you can create your own and have them registered along with the associated formatting logic. + You can see examples of the DateTimeFormat annotation in the Spring Travel and in the Petcare along with other samples in the Spring Samples repository. + + + + Working With Dates + + The DateTimeFormat annotation implies use of Joda Time. + 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 DateTimeFormat annotation on the other hand provides more fine-grained control where it is necessary to deviate from the default. + + + For more information on working with Spring 3 type conversion and formatting please refer to the relevant sections of the Spring documentation. diff --git a/spring-webflow-samples/booking-faces/src/main/webapp/WEB-INF/flows/main/main-flow.xml b/spring-webflow-samples/booking-faces/src/main/webapp/WEB-INF/flows/main/main-flow.xml index e0fa334e..ff26cf39 100755 --- a/spring-webflow-samples/booking-faces/src/main/webapp/WEB-INF/flows/main/main-flow.xml +++ b/spring-webflow-samples/booking-faces/src/main/webapp/WEB-INF/flows/main/main-flow.xml @@ -7,7 +7,7 @@ - +