From 28f9511b6830e8bb4e2afc70b1cc796b68014eeb Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Fri, 5 Aug 2022 14:15:13 +0300 Subject: [PATCH] Update reference docs for 3.0 --- src/dist/readme.txt | 2 +- .../flow-definition-field-mappings.adoc | 506 ------------------ src/reference/index.adoc | 4 - src/reference/overview.adoc | 18 +- src/reference/whatsnew.adoc | 263 --------- 5 files changed, 12 insertions(+), 781 deletions(-) delete mode 100644 src/reference/flow-definition-field-mappings.adoc delete mode 100644 src/reference/whatsnew.adoc diff --git a/src/dist/readme.txt b/src/dist/readme.txt index 942f255a..ac5ee0f1 100644 --- a/src/dist/readme.txt +++ b/src/dist/readme.txt @@ -20,7 +20,7 @@ It is a powerful controller engine that addresses the "C" in MVC. 2. RELEASE NOTES ---------------- -Spring Web Flow 2.5 requires JDK 1.8 and Spring Framework 5.0 to run. +Spring Web Flow 3.0 requires JDK 17 and Spring Framework 6.0 to run. Release distribution contents: diff --git a/src/reference/flow-definition-field-mappings.adoc b/src/reference/flow-definition-field-mappings.adoc deleted file mode 100644 index 02397615..00000000 --- a/src/reference/flow-definition-field-mappings.adoc +++ /dev/null @@ -1,506 +0,0 @@ -:sectnums!: - -[appendix] -[[_field_mappings]] -== Flow Definition Language 1.0 to 2.0 Mappings - -The flow definition language has changed since the 1.0 release. -This is a listing of the language elements in the 1.0 release and how they map to elements in the 2.0 release. -While most of the changes are semantic, there are a few structural changes. -See the upgrade guide for more details about changes between Web Flow 1.0 and 2.0. - -.Mappings -[cols="20,^20,60", options="header"] -|=== -| SWF 1.0 -| SWF 2.0 -| Comments - -|_action_ -|_*_ -|Use ``. - -^| bean -| * -| - -^| name -| * -| - -^| method -| * -| - - -|__action-state__ -|__action-state__ -| - -^| id -| id -| - - -^| * -| parent -| - -| _argument_ -| _*_ -| Use ``. - -^| expression -| -| - -^| parameter-type -| -| - -| _attribute_ -| _attribute_ -| - -^| name -| name -| - -^| type -| type -| - -^| value -| value -| - -| _attribute-mapper_ -| _*_ -| Input and output elements can be in flows or sub-flows directly. - -^| bean -| * -| Now `subflow-attribute-mapper` attribute on `subflow-state`. - -| _bean-action_ -| _*_ -| use - -^| bean -| * -| - -^| name -| * -| - -^| method -| * -| - -| _decision-state_ -| _decision-state_ -| - -^| id -| id -| - -^| * -| parent -| - -| _end-actions_ -| _on-end_ -| - -| _end-state_ -| _end-state_ -| - -^| id -| id -| - -^| view -| view -| - -^| * -| parent -| - -^| * -| commit -| - -| _entry-actions_ -| _on-entry_ -| - -| _evaluate-action_ -| _evaluate_ -| - -^| expression -| expression -| - -^| name -| * -| Use ` `. - -^| * -| result -| - -^| * -| result-type -| - -| _evaluation-result_ -| _*_ -| Use ``. - -^| name -| * -| - -^| scope -| * -| - -| _exception-handler_ -| _exception-handler_ -| - -^| bean -| bean -| - -| _exit-actions_ -| _on-exit_ -| - -| _flow_ -| _flow_ -| - -^| * -| start-state -| - -^| * -| parent -| - -^| * -| abstract -| - -| _global-transitions_ -| _global-transitions_ -| - -| _if_ -| _if_ -| - -^| test -| test -| - -^| then -| then -| - -^| else -| else -| - -| _import_ -| _bean-import_ -| - -^| resource -| resource -| - -| _inline-flow_ -| _*_ -| Convert to new top-level flow - -^| id -| * -| - -| _input-attribute_ -| _input_ -| - -^| name -| name -| - -^| scope -| * -| Prefix name with scope ``. - -^| required -| required -| - -^| * -| type -| - -^| * -| value -| - -| _input-mapper_ -| _*_ -| Inputs can be in flows and subflows directly. - -| _mapping_ -| _input or output_ -| - -^| source -| name or value -| Name when in flow element, value when in the `subflow-state` element. - -^| target -| name or value -| Value when in flow element, name when in the `subflow-state` element. - -^| target-collection -| * -| No longer supported - -^| from -| * -| Detected automatically - -^| to -| type -| - -^| required -| required -| - -| _method-argument_ -| _*_ -| Use ``. - -| _method-result_ -| _*_ -| Use ``. - -^| name -| * -| - -^| scope -| * -| - -| _output-attribute_ -| _output_ -| - -^| name -| name -| - -^| scope -| * -| Prefix name with scope ``. - -^| required -| required -| - -^| * -| type -| - -^| * -| value -| - -| _output-mapper_ -| _*_ -| Output can be in flows and subflows directly. - -| _render-actions_ -| _on-render_ -| - -| _set_ -| _set_ -| - -^| attribute -| name -| - -^| scope -| * -| Prefix name with scope ``. - -^| value -| value -| - -^| name -| * -| Use ` `. - -^| * -| type -| - -| _start-actions_ -| _on-start_ -| - -| _start-state_ -| _*_ -| Now `` or defaults to the first state in the flow. - -^| idref -| * -| - -| _subflow-state_ -| _subflow-state_ -| - -^| id -| id -| - -^| flow -| subflow -| - -^| * -| parent -| - -^| * -| subflow-attribute-mapper -| - -| _transition_ -| _transition_ -| - -^| on -| on -| - -^| on-exception -| on-exception -| - -^| to -| to -| - -^| * -| bind -| - -^| * -| validate -| - -^| * -| history -| - -| _value_ -| _value_ -| - -| _var_ -| _var_ -| - -^| name -| name -| - -^| class -| class -| - -^| scope -| * -| Always flow scope - -^| bean -| * -| All Spring beans can be resolved with EL - -| _view-state_ -| _view-state_ -| - -^| id -| id -| - -^| view -| view -| - -^| * -| parent -| - -^| * -| redirect -| - -^| * -| popup -| - -^| * -| model -| - -^| * -| history -| - -| _*_ -| _persistence-context_ -| - -| _*_ -| _render_ -| - -^| * -| fragments -| - -| _*_ -| _secured_ -| - -^| * -| attributes -| - -^| * -| match -| -|=== - -:sectnums: diff --git a/src/reference/index.adoc b/src/reference/index.adoc index d75d49b7..1d76eed2 100644 --- a/src/reference/index.adoc +++ b/src/reference/index.adoc @@ -26,8 +26,6 @@ This reference guide shows you how to use and extend Spring Web Flow. include::overview.adoc[] -include::whatsnew.adoc[] - include::defining-flows.adoc[] include::el.adoc[] @@ -51,5 +49,3 @@ include::spring-js.adoc[] include::spring-faces.adoc[] include::testing.adoc[] - -include::flow-definition-field-mappings.adoc[] diff --git a/src/reference/overview.adoc b/src/reference/overview.adoc index 5c1b2e76..11861ac4 100644 --- a/src/reference/overview.adoc +++ b/src/reference/overview.adoc @@ -8,18 +8,18 @@ It also covers extending the framework and the overall architectural model. [[_system_requirements]] === Web Flow Requirements -* Java 1.8 or higher. -* Spring 5.0 or higher. +* Java 17 or higher. +* Spring Framework 6.0 or higher. === Resources You can ask questions and interact on StackOverflow by using the designated tags. See https://stackoverflow.com/questions/tagged/spring-webflow[Spring Web Flow at StackOverflow]. -You can report bugs and make requests by using the https://jira.spring.io[Spring Issue Tracker]. +You can report bugs and make requests by using the project https://jira.spring.io/projects/SWF[issue tracker]. You can submit pull requests and work with the source code. -See https://github.com/spring-projects/spring-webflow[Spring Web Flow on Github]. +See https://github.com/spring-projects/spring-webflow[spring-webflow on GitHub]. [[_jars_mvn_central]] === Accessing Web Flow Artifacts from Maven Central @@ -36,11 +36,12 @@ To access Web Flow jars from Maven Central, declare the following dependency in org.springframework.webflow spring-webflow - x.y.z.RELEASE + x.y.z ---- ==== +//// If you use JavaServer Faces, declare the following dependency in your pom (includes the `spring-binding` and `spring-webflow` transitive dependencies): ==== @@ -50,10 +51,11 @@ If you use JavaServer Faces, declare the following dependency in your pom (inclu org.springframework.webflow spring-faces - x.y.z.RELEASE + x.y.z ---- ==== +//// === Accessing Nightly Builds and Milestone Releases @@ -86,11 +88,12 @@ Then you need to declare the following dependency: org.springframework.webflow spring-webflow - x.y.z.BUILD-SNAPSHOT + x.y.z-SNAPSHOT ---- ==== +//// Also, if you use JSF, you need to add the following dependency: ==== @@ -104,3 +107,4 @@ Also, if you use JSF, you need to add the following dependency: ---- ==== +//// \ No newline at end of file diff --git a/src/reference/whatsnew.adoc b/src/reference/whatsnew.adoc deleted file mode 100644 index 2cceb3e9..00000000 --- a/src/reference/whatsnew.adoc +++ /dev/null @@ -1,263 +0,0 @@ -[[_whatsnew]] -== What's New - -This section covers the changes that have been included in the last few versions: - -* <<_whatsnew_swf_250>> -* <<_whatsnew_swf_240>> -* <<_whatsnew_swf_230>> -* <<_whatsnew_swf_220>> - -[[_whatsnew_swf_250]] -=== Spring Web Flow 2.5 - -This release provides an upgrade path to Spring Framework 5 that in turn requires Java 8+, Servlet 3.1, Hibernate 5, Tiles 3. -See the https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-Spring-Framework-5.x[Spring Framework wiki] for more details. -The https://github.com/spring-projects/spring-webflow-samples[samples repository] has been upgraded to Spring Web Flow 2.5. - -As of 2.5, there is no longer a `spring-js` module. -The classes from that module have been kept but moved to new packages in the `spring-webflow` module. -The `spring-js-resources` module is available as an optional module that you can explicitly include. - -This release requires JSF 2.2 or higher. - -[[_whatsnew_swf_240]] -=== Spring Web Flow 2.4 - -This release requires JDK 1.6. - -[[_whatsnew_swf_java_config]] -==== Java-based Configuration - -Spring Web Flow now supports a Java-based alternative for its system configuration. -See the updated <<_system_setup>>. - -See the https://github.com/spring-projects/spring-webflow-samples/tree/main/booking-mvc[booking-mvc] and https://github.com/spring-projects/spring-webflow-samples/tree/main/booking-faces[booking-faces] samples that have been updated to use all Java configuration. - -[[_whatsnew_swf_mvcflash]] -==== Spring MVC Flash Scope Integration - -When a flow ends, it can now redirect to a Spring MVC controller after saving attributes in Spring MVC's flash scope for the controller to access. - -See <<_spring_mvc_flash_output>>. - -[[_whatsnew_partial_validation]] -==== Partial JSR-303 Bean Validation - -A flow definition can apply partial validation on the model through the validation-hints attribute supported on view state and transition elements. - -See <<_view_validation_jsr303_partial>>. - -[[_whatsnew_hibernate4]] -==== Hibernate Support - -`HibernateFlowExecutionListener` now supports Hibernate 4 in addition to Hibernate 3. - -As of 2.4.4, `HibernateFlowExecutionListener` also works with Hibernate 5. - -[[_whatsnew_tiles3]] -==== Tiles 3 Support - -`AjaxTilesView` now supports Tiles 3 in addition to Tiles 2.2. - -[[_whatsnew_swf_jsf20]] -==== Minimum JSF 2.0 Requirement - -Java ServerFaces version 1.2 and earlier are no longer supported by Spring Web Flow. -If you have not done so already, you need to upgrade to JSF 2.0 or later. -In addition, the Spring Faces components that were previously provided with JSF 1.2 for progressive AJAX enhancements have been removed in this release. - -[[_whatsnew_swf_jsf20_portlet]] -==== Portlet API 2.0 and JSF 2.0 support - -The internal Portlet integration introduced in Spring Web Flow 2.2 has been upgraded for JSF 2.0 compatibility. -Some of the more advanced JSF 2.0 features, such as partial state saving, are not supported in a Portlet environment. -However, existing applications can now upgrade to the minimum required JSF version. -Upgraded projects need to ensure that the `` elements is included as part of their Spring configuration. - -[[_whatsnew_deprecation]] -==== Deprecations - -This release deprecates `Spring.js`. -The deprecation includes the entire `spring-js-resources` module, including `Spring.js` and `Spring-Dojo.js` and the bundled Dojo and CSS Framework. -Also deprecated is the `SpringJavascriptAjaxHandler` from the `spring-js` module. -The rest of `spring-js` (for example, `AjaxHandler`` and `AjaxTilesView`), will be folded into `spring-webflow` in a future release. - -OGNL support is now deprecated. - -[[_whatsnew_swf_230]] -=== Spring Web Flow 2.3 - -Version 2.3 includes changes to the following topics: - -* <<_whatsnew_swf_embedded_flow>> -* <<_whatsnew_jsr303>> -* <<_whatsnew_pc_propagation>> -* <<_whatsnew_portlet_resource_requests>> -* <<_whatsnew_conversation_manager>> -* <<_whatsnew_redirect_in_same_state>> -* <<_whatsnew_samples>> - -[[_whatsnew_swf_embedded_flow]] -==== Embedding A Flow On A Page - -By default, Web Flow does a client-side redirect upon entering every view state. -That makes it impossible to embed a flow on a page or within a modal dialog and execute more than one view state without causing a full-page refresh. -Web Flow now supports launching a flow in "`embedded`" mode. -In this mode, a flow can transition to other view states without a client-side redirect during Ajax requests. -See <<_spring_mvc_embedded_flow>> and <<_spring_faces_embedded_mode>>. - -[[_whatsnew_jsr303]] -==== Support For JSR-303 Bean Validation - -Support for the JSR-303 Bean Validation API is now available, building on equivalent support available in Spring MVC. -See <<_view_validate>> for more details. - -[[_whatsnew_pc_propagation]] -==== Flow-Managed Persistence Context Propagation - -Starting with Web Flow 2.3, a flow managed `PersistenceContext` is automatically extended (propagated) to sub-flows, assuming the sub-flow also has the feature enabled as well. -See <<_flow_managed_persistence_propagation>>. - -[[_whatsnew_portlet_resource_requests]] -==== Portlet 2.0 Resource Requests - -Support for Portlet 2.0 resource requests has now been added, enabling Ajax requests with partial rendering. -URLs for such requests can be prepared with the `` tag in JSP pages. -Server-side processing is similar to combining an action and a render request in a single request. -Unlike a render request, the response from a resource request includes content from the target portlet only. - -[[_whatsnew_conversation_manager]] -==== Custom ConversationManager - -The `` element now provides a conversation-manager attribute that accepts a reference to a `ConversationManager` instance. - -[[_whatsnew_redirect_in_same_state]] -==== Redirect In Same State - -By default, Web Flow does a client-side redirect when remaining in the same view state as long as the current request is not an Ajax request. -This is useful after form validation failure. -Hitting Refresh or Back does not result in browser warnings. -Hence, this behavior is usually desirable. -However, a new flow execution attribute makes it possible to disable it, and that may also be necessary in some cases specific to JSF applications. -See <<_spring_faces_redirect_in_same_state>>. - -[[_whatsnew_samples]] -==== Samples - -The process for building the samples included with the distribution has been simplified. -Maven can be used to build all samples in one step. -Eclipse settings include source code references to simplify debugging. - -You can access additional samples as follows: - -==== -[source,xml] ----- -mkdir spring-samples -cd spring-samples -svn co https://src.springframework.org/svn/spring-samples/webflow-primefaces-showcase -cd webflow-primefaces-showcase -mvn package -# import into Eclipse ----- -[source,xml] ----- -mkdir spring-samples -cd spring-samples -svn co https://src.springframework.org/svn/spring-samples/webflow-showcase -cd webflow-showcase -mvn package -# import into Eclipse ----- -==== - -[[_whatsnew_swf_220]] -=== Spring Web Flow 2.2 - -Version 2.3 includes changes to the following topics: - -* <<_whatsnew_jsf2>> -* <<_whatsnew_sec>> -* <<_whatsnew_versions>> -* <<_whatsnew_jsf_portlet>> - -[[_whatsnew_jsf2]] -==== JSF 2 Support - -Building on version 2.1, Spring Web Flow version 2.2 adds support for core JSF 2 features. -The following features that were not supported in 2.1 are now available: - -* Partial state saving -* JSF 2 resource request handling -* JSF 2 Ajax requests - -At this point, support for JSF 2 is considered comprehensive, although not it does not cover every JSF 2 feature. -The excluded items are mostly features that overlap with the core value that Web Flow provides, such as those relating to navigation and state management. - -See <<_spring_faces_webflow_config>> for important configuration changes. -Note that partial state saving is only supported with Sun Mojarra 2.0.3 or later. -It is not yet supported with Apache MyFaces. -This is due to the fact MyFaces was not as easy to customize with regards to how component state is stored. -We will work with Apache MyFaces to provide this support. -In the meantime, you need to use the `jakarta.faces.PARTIAL_STATE_SAVING` context parameter in `web.xml` to disable partial state saving with Apache MyFaces. - -===== Travel Sample With the PrimeFaces Components - -The main Spring Travel sample that demonstrates Spring Web Flow and JSF support is now built on JSF 2 and components from the PrimeFaces component library. -See the booking-faces sample in the distribution. - -You can find additional samples at the Spring Web Flow - Prime Faces https://src.springframework.org/svn/spring-samples/webflow-primefaces-showcase[Showcase], an SVN repository within the https://src.springframework.org/svn/spring-samples[spring-samples] repository. -You can use the following commands to check out and build: - -==== -[source] ----- -svn co https://src.springframework.org/svn/spring-samples/webflow-primefaces-showcase -cd webflow-primefaces-showcase -mvn package ----- -==== - -[[_whatsnew_sec]] -==== Spring Security Facelets Tag Library - -A new Spring Security tag library is available for use with with JSF 2.0 or with JSF 1.2 Facelets views. -It provides an `` tag as well as several EL functions. -See <<_spring_faces_security_taglib>> for more details. - -[[_whatsnew_versions]] -==== Spring JavaScript Updates - -A number of changes have been made to the Spring JavaScript library. - -===== Deprecated `ResourcesServlet` - -Starting with Spring 3.0.4, the Spring Framework includes a replacement for `ResourcesServlet`. -See the Spring Framework documentation for details on the custom MVC namespace -- specifically, the new https://docs.spring.io/spring/docs/3.0.x/spring-framework-reference/html/mvc.html#mvc-static-resources[`resources`]element. - -===== Dojo 1.5 and dojox - -The bundled custom Dojo build is upgraded to version 1.5. -It now includes `dojox`. - -Note that applications are generally encouraged to prepare their own custom Dojo build for optimized performance, depending on what parts of Dojo are commonly used together. -For examples, see the https://src.springframework.org/svn/spring-webflow/branches/spring-webflow-2.2-maintenance/spring-js-resources/scripts/dojo[scripts] used by Spring Web Flow to prepare its own custom Dojo build. - -===== Two Spring JS Artifacts - -The `spring-js` artifact has been split in two. The new artifact (`spring-js-resources`) contains client side resource (`.js`, `.css`, and so on), while the existing artifact (`spring-js`) contains server-side Java code only. - -Applications preparing their own custom Dojo build have an option now to avoid including `spring-js-resources` and put `Spring.js` and `Spring-Dojo.js` directly under the root of their web application. - -===== Client Resources Moved into META-INF/web-resources - -Bundled client resources (`.js`, `.css`, and so on) have been moved to `META-INF/web-resources` from their previous location under `META-INF`. -This change is transparent for applications but results in simpler and safer configuration when using the new resource handling mechanism available in Spring 3.0.4. - -[[_whatsnew_jsf_portlet]] -==== JSF Portlet Support - -In previous versions of Spring Web Flow, support for JSF Portlets relied on a Portlet Bridge for JSF implementation and was considered experimental. -Spring Web Flow 2.2 adds support for JSF Portlets based on its own internal Portlet integration targeting Portlet API 2.0 and JSF 1.2 environments. -The Spring Web Flow Travel JSF Portlets sample has been successfully tested on the Apache Pluto portal container.