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

Update reference docs for 3.0

Browse Source
This commit is contained in:
Rossen Stoyanchev
2022-08-05 14:15:13 +03:00
parent fb82f141ab
commit 28f9511b68
5 changed files with 12 additions and 781 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/dist/readme.txt vendored
View File

@@ -20,7 +20,7 @@ It is a powerful controller engine that addresses the "C" in MVC.
2. RELEASE NOTES 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: Release distribution contents:

506
src/reference/flow-definition-field-mappings.adoc
View File

@@ -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 `<evaluate />`.
^| bean
| *
|
^| name
| *
|
^| method
| *
|
|__action-state__
|__action-state__
|
^| id
| id
|
^| *
| parent
|
| _argument_
| _*_
| Use `<evaluate expression="func(arg1, arg2, ...)"/>`.
^| 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 <evaluate />
^| 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 `<evaluate ...> <attribute name=`"name`" value="..." /> </evaluate>`.
^| *
| result
|
^| *
| result-type
|
| _evaluation-result_
| _*_
| Use `<evaluate result="..." />`.
^| 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 `<input name="flowScope.foo" />`.
^| 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 `<evaluate expression="func(arg1, arg2, ...)"/>`.
| _method-result_
| _*_
| Use `<evaluate result="..." />`.
^| name
| *
|
^| scope
| *
|
| _output-attribute_
| _output_
|
^| name
| name
|
^| scope
| *
| Prefix name with scope `<output name="flowScope.foo" />`.
^| 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 `<set name="flowScope.foo" />`.
^| value
| value
|
^| name
| *
| Use `<set ...> <attribute name=`"name`" value="..." /> </set>`.
^| *
| type
|
| _start-actions_
| _on-start_
|
| _start-state_
| _*_
| Now `<flow start-state="...">` 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:

4
src/reference/index.adoc
View File

@@ -26,8 +26,6 @@ This reference guide shows you how to use and extend Spring Web Flow.
include::overview.adoc[] include::overview.adoc[]
include::whatsnew.adoc[]
include::defining-flows.adoc[] include::defining-flows.adoc[]
include::el.adoc[] include::el.adoc[]
@@ -51,5 +49,3 @@ include::spring-js.adoc[]
include::spring-faces.adoc[] include::spring-faces.adoc[]
include::testing.adoc[] include::testing.adoc[]
include::flow-definition-field-mappings.adoc[]

18
src/reference/overview.adoc
View File

@@ -8,18 +8,18 @@ It also covers extending the framework and the overall architectural model.
[[_system_requirements]] [[_system_requirements]]
=== Web Flow Requirements === Web Flow Requirements
* Java 1.8 or higher. * Java 17 or higher.
* Spring 5.0 or higher. * Spring Framework 6.0 or higher.
=== Resources === Resources
You can ask questions and interact on StackOverflow by using the designated tags. 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]. 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. 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]] [[_jars_mvn_central]]
=== Accessing Web Flow Artifacts from Maven 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
<dependency> <dependency>
<groupId>org.springframework.webflow</groupId> <groupId>org.springframework.webflow</groupId>
<artifactId>spring-webflow</artifactId> <artifactId>spring-webflow</artifactId>
<version>x.y.z.RELEASE</version> <version>x.y.z</version>
</dependency> </dependency>
---- ----
==== ====
////
If you use JavaServer Faces, declare the following dependency in your pom (includes the `spring-binding` and `spring-webflow` transitive dependencies): 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
<dependency> <dependency>
<groupId>org.springframework.webflow</groupId> <groupId>org.springframework.webflow</groupId>
<artifactId>spring-faces</artifactId> <artifactId>spring-faces</artifactId>
<version>x.y.z.RELEASE</version> <version>x.y.z</version>
</dependency> </dependency>
---- ----
==== ====
////
=== Accessing Nightly Builds and Milestone Releases === Accessing Nightly Builds and Milestone Releases
@@ -86,11 +88,12 @@ Then you need to declare the following dependency:
<dependency> <dependency>
<groupId>org.springframework.webflow</groupId> <groupId>org.springframework.webflow</groupId>
<artifactId>spring-webflow</artifactId> <artifactId>spring-webflow</artifactId>
<version>x.y.z.BUILD-SNAPSHOT</version> <version>x.y.z-SNAPSHOT</version>
</dependency> </dependency>
---- ----
==== ====
////
Also, if you use JSF, you need to add the following dependency: 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:
</dependency> </dependency>
---- ----
==== ====
////

263
src/reference/whatsnew.adoc
View File

@@ -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 `<faces:resources>` 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 `<portlet:resourceURL>` 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 `<flow-execution-repository>` 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 `<authorize>` 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.