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

Update reference

Browse Source 
Issue: SWF-1702
This commit is contained in:
Rossen Stoyanchev
2018-02-08 20:53:13 -05:00
parent 9328890eaf
commit 959fbaddf9
7 changed files with 57 additions and 285 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/dist/javascript-copyright.txt vendored
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2004-2008 the original author or authors.
* Copyright 2004-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.

4
src/dist/notice.txt vendored
View File

@@ -1,11 +1,11 @@
Spring Web Flow ${version}
Copyright (c) 2002-${copyright} SpringSource, a division of VMware, Inc.
Copyright 2002-${copyright} the original author or authors.
This product is licensed to you under the Apache License, Version 2.0
(the "License"). You may not use this product except in compliance with
the License.
This product may include a number of subcomponents with separate
This product may include a number of sub-components with separate
copyright notices and license terms. Your use of the source code for
these subcomponents is subject to the terms and conditions of the
subcomponent's license, as noted in the license.txt file.

50
src/dist/readme.txt vendored
View File

@@ -1,6 +1,6 @@
SPRING WEB FLOW ${version}
--------------------------
http://www.springframework.org/webflow
http://projects.spring.io/spring-webflow/
1. INTRODUCTION
---------------
@@ -34,18 +34,18 @@ Spring Web Flow is released under the terms of the Apache Software License (see
3. GETTING STARTED
------------------
Current samples:
https://github.com/SpringSource/spring-webflow-samples.
https://github.com/spring-projects/spring-webflow-samples.
4. OBTAINING RELEASE JARS WITH MAVEN OR IVY
-------------------------------------------
4. OBTAINING RELEASE JARS THROUGH MAVEN REPOSITORY
--------------------------------------------------
Release versions of Spring Web Flow artifacts are available via Maven Central.
For milestones and snapshots only (and for Ivy dependencies) you'll need to use the
SpringSource repository. Add the following repository to your Maven pom.xml:
For milestones and snapshots only you'll need to use the Spring repository.
Add the following repository to your Maven pom.xml:
<repository>
<id>springsource-repository</id>
<name>Spring project releases, milestones, and snapshots</name>
<id>spring</id>
<name>Spring Snapshots</name>
<url>http://repo.spring.io/snapshot</url>
</repository>
@@ -73,36 +73,6 @@ If using JSF all you need to include is:
<version>${version}</version>
</dependency>
To access jars using Ivy, add the following repositories to your Ivy config:
<url name="com.springsource.repository.bundles.release">
<ivy pattern="http://repository.springsource.com/ivy/bundles/release/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
<artifact pattern="http://repository.springsource.com/ivy/bundles/release/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
</url>
<url name="com.springsource.repository.bundles.external">
<ivy pattern="http://repository.springsource.com/ivy/bundles/external/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
<artifact pattern="http://repository.springsource.com/ivy/bundles/external/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
</url>
Then declare the following dependencies in your ivy.xml:
<dependency org="org.springframework.webflow" name="org.springframework.binding" rev="${version}" conf="compile->runtime" />
<dependency org="org.springframework.webflow" name="org.springframework.js" rev="${version}" conf="compile->runtime" />
<dependency org="org.springframework.webflow" name="org.springframework.webflow" rev="${version}" conf="compile->runtime" />
If using JavaServerFaces:
<dependency org="org.springframework.webflow" name="org.springframework.faces" rev="${version}" conf="compile->runtime" />
For more information see the reference documentation and the SpringSource Repository FAQ:
https://github.com/spring-projects/spring-framework/wiki/Spring-repository-FAQ
5. ADDITIONAL RESOURCES
-----------------------
The Spring Web Flow homepage is located at:
http://projects.spring.io/spring-webflow/
The Spring Web Flow community forums are located at:
http://forum.spring.io/
For more details see the following Spring Framework wiki page:
https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Artifacts

67
src/reference/overview.xml
View File

@@ -19,10 +19,10 @@
<sect1 xml:id="system-requirements">
<title>What Web Flow requires to run</title>
<para>
Java 1.6 or higher.
Java 1.8 or higher.
</para>
<para>
Spring 3.2 or higher.
Spring 5.0 or higher.
</para>
</sect1>
<sect1 xml:id="resources">
@@ -48,8 +48,7 @@
build system for your web development project.
</para>
<para>
To access Web Flow jars from Maven Central, declare the following dependency in your pom (includes
transitive dependencies "spring-binding"):
To access Web Flow jars from Maven Central, declare the following dependency in your pom:
</para>
<programlisting language="xml"><![CDATA[
<dependency>
@@ -72,54 +71,6 @@
]]>
</programlisting>
</sect1>
<sect1 xml:id="jars-ivy">
<title>How to access Web Flow artifacts with Ivy</title>
<para>
To access Spring Web Flow jars with Ivy, add the following repositories to your Ivy config:
</para>
<programlisting language="xml"><![CDATA[
<url name="com.springsource.repository.bundles.release">
<ivy pattern="http://repository.springsource.com/ivy/bundles/release/
[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
<artifact pattern="http://repository.springsource.com/ivy/bundles/release/
[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
</url>
<url name="com.springsource.repository.bundles.external">
<ivy pattern="http://repository.springsource.com/ivy/bundles/external/
[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
<artifact pattern="http://repository.springsource.com/ivy/bundles/external/
[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
</url>]]>
</programlisting>
<para>
To access Spring Web Flow jars as well as 3rd party dependencies with Ivy, add the following repository to your Ivy config:
</para>
<programlisting language="xml"><![CDATA[
<url name="springsource-repository">
<ivy pattern="http://repo.spring.io/libs-release/[organization]/[module]/[revision]/[type]s/ivy-[revision].xml" />
<artifact pattern="http://repo.spring.io/libs-release/[organization]/[module]/[revision]/[type]s/[module](-[classifier])-[revision].[ext]" />
</url>]]>
</programlisting>
<para>
Then declare the following dependencies in your ivy.xml:
</para>
<programlisting language="xml"><![CDATA[
<dependency org="org.springframework.webflow" name="org.springframework.binding"
rev="x.y.z.RELEASE" conf="compile->runtime" />
<dependency org="org.springframework.webflow" name="org.springframework.js"
rev="x.y.z.RELEASE" conf="compile->runtime" />
<dependency org="org.springframework.webflow" name="org.springframework.webflow"
rev="x.y.z.RELEASE" conf="compile->runtime" />]]>
</programlisting>
<para>
If using JavaServer Faces, declare the following dependency in your pom (also adds the above dependencies):
</para>
<programlisting language="xml"><![CDATA[
<dependency org="org.springframework.webflow" name="org.springframework.faces"
rev="x.y.z.RELEASE" conf="compile->runtime" />]]>
</programlisting>
</sect1>
<sect1>
<title>How to access nightly builds and milestone releases</title>
<para>
@@ -134,8 +85,8 @@
</para>
<programlisting language="xml"><![CDATA[
<repository>
<id>springsource-repository</id>
<name>Spring project snapshots, milestones, and releases</name>
<id>spring</id>
<name>Spring Repository</name>
<url>http://repo.spring.io/snapshot</url>
</repository>]]>
</programlisting>
@@ -143,12 +94,6 @@
Then declare the following dependencies:
</para>
<programlisting language="xml"><![CDATA[
<dependency>
<groupId>org.springframework.webflow</groupId>
<artifactId>spring-binding</artifactId>
<version>x.y.z.BUILD-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.springframework.webflow</groupId>
<artifactId>spring-webflow</artifactId>
@@ -156,7 +101,7 @@
</dependency>]]>
</programlisting>
<para>
And if using JavaServerFaces:
And if using JSF:
</para>
<programlisting language="xml"><![CDATA[
<dependency>

159
src/reference/spring-faces.xml
View File

@@ -11,121 +11,12 @@ xsi:schemaLocation="
<sect1 xml:id="spring-faces-introduction">
<title>Introduction</title>
<para>Spring Web Flow provides a JSF integration that simplifies using JSF
with Spring. It lets you use the JSF UI Component Model with Spring MVC
and Spring Web Flow controllers. Along with the JSF integration Spring Web
Flow provides a Spring Security tag library for use in JSF environments
(see <xref linkend="spring-faces-security-taglib" /> for more details).
<para>
Spring Web Flow provides a JSF integration that lets you use the JSF UI
Component Model with Spring Web Flow controllers. Web Flow also provides
a Spring Security tag library for use in JSF environments,
see <xref linkend="spring-faces-security-taglib" /> for more details.
</para>
<para>Starting with Spring Web Flow version 2.4, JSF integration requires
JSF v2.0 or above. Both Sun Mojarra and Apache MyFaces runtime environments
are supported.</para>
</sect1>
<sect1 xml:id="spring-faces-integration">
<title>JSF Integration For Spring Developers</title>
<para>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>JSF applications using Spring Web Flow applications gain benefits in
the following areas: <orderedlist>
<listitem>
<para>Managed bean facility</para>
</listitem>
<listitem>
<para>Scope management</para>
</listitem>
<listitem>
<para>Event handling</para>
</listitem>
<listitem>
<para>Navigation</para>
</listitem>
<listitem>
<para>Modularization and packaging of views</para>
</listitem>
<listitem>
<para>Cleaner URLs</para>
</listitem>
<listitem>
<para>Model-level validation</para>
</listitem>
</orderedlist> 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 <xref
linkend="defining-flows" />.</para>
</sect1>
<sect1 xml:id="spring-faces-upgrade-from-swf23">
<title>Upgrading from Spring Web Flow 2.3</title>
<para>If you are upgrading from Spring Web Flow 2.3 or earlier you may need to
update several aspects of your project. JSF 2.0 is now a minimum requirement
and as result some components from previous releases are no longer included.</para>
<sect2 xml:id="spring-faces-upgrade-from-swf23-components">
<title>Spring Faces Components</title>
<para>Previous releases of Spring Web Flow shipped with a component library
which provided Ajax and client-side validation capabilities for JSF 1.2
environments. Applications using these components will need to switch to a
3rd party JSF component library such as PrimeFaces or RichFaces.
Components that have been removed include <code>&lt;sf:clientTextValidator&gt;</code>,
<code>&lt;sf:clientNumberValidator&gt;</code>, <code>&lt;sf:clientDateValidator&gt;</code>,
<code>&lt;sf:validateAllOnClick&gt;</code>, <code>&lt;sf:resource&gt;</code> and
<code>&lt;sf:resourceGroup&gt;</code>.
The <code>swf-booking-faces</code> sample in the Spring Web Flow distribution
shows an example built with PrimeFaces components.</para>
</sect2>
<sect2 xml:id="spring-faces-upgrade-from-swf23-faces-config">
<title>Configuring faces-config.xml</title>
<para>If your application defines a <code>faces-config.xml</code> file you should
ensure that the correct schema version is specified. In addition you should remove
any <code>FaceletViewHandler</code> references as Facelets are now the default rendering
technology for JSF 2.0</para>
<programlisting language="xml">
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;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"&gt;
&lt;/faces-config&gt;
</programlisting>
</sect2>
<sect2 xml:id="spring-faces-upgrade-from-swf23-thirdpartylibraries">
<title>Third-party Libraries</title>
<para>Previous releases of Spring Web Flow would often require additional configuration in order
for 3rd party component libraries to work correctly. JSF 2.0 introduced standard resource
loading mechanisms that removes the need for such custom configuration. As long as you
have a <code>&lt;faces:resources&gt;</code> element in your Spring configuration, libraries
such as RichFaces or Apache Trinidad you should work.</para>
</sect2>
<sect2 xml:id="spring-faces-upgrade-from-swf23-security-taglib">
<title>Spring Security Facelets Tag Library</title>
<para>If you have a previously configured <code>/WEB-INF/springsecurity.taglib.xml</code> file
you may need to update the contents. See <xref linkend="spring-faces-security-taglib"/> for
details.</para>
</sect2>
</sect1>
<sect1 xml:id="spring-faces-config-web.xml">
@@ -737,7 +628,7 @@ mvn package
with these components JSF must take complete control of parsing multi-part requests and Spring MVC's
<code>MultipartResolver</code> cannot be used.</para>
<para>Spring Web Flow has been tested with file upload components from PrimeFaces and RichFaces. Check the
<para>Spring Web Flow has been tested with file upload components from PrimeFaces. Check the
documentation of your JSF component library for other providers to see how to configure file upload.</para>
<sect2>
@@ -753,42 +644,16 @@ mvn package
<filter-mapping>
<filter-name>PrimeFaces FileUpload Filter</filter-name>
<servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
</filter-mapping>]]>
</filter-mapping>
<context-param>
<param-name>primefaces.UPLOADER</param-name>
<param-value>commons</param-value>
</context-param>]]>
</programlisting>
<para>For more details refer to the
<link xl:href="http://primefaces.org/documentation.html">PrimeFaces documentation</link>.</para>
</sect2>
<sect2>
<title>File Uploads with RichFaces</title>
<para>RichFaces provides a <code>&lt;rich:fileUpload&gt;</code> component for uploading files. No
special configuration is required to use the component, however, you will need to perform
some additional steps in your <code>fileUploadListener</code>.</para>
<para>Here is some typical XHTML markup. In this example the <code>fileUploadBean</code> refers
to Spring singleton bean.</para>
<programlisting language="xml"><![CDATA[<rich:fileUpload id="upload"
fileUploadListener="#{fileUploadBean.listener}"
acceptedTypes="jpg, gif, png, bmp">
</rich:fileUpload>]]></programlisting>
<para>Within your <code>fileUploadBean</code> you need to tell Web Flow that the response has been
handled and that it should not attempt any redirects. The <interfacename>org.springframework.webflow.context.ExternalContext</interfacename>
interface provides a <code>recordResponseComplete()</code> for just such purposes.</para>
<para>In addition, it is imperative that some partial response data is returned to the client. If your
<code>&lt;rich:fileUpload&gt;</code> component does not specify a <code>render</code> attribute you
may need to call <code>processPartial(PhaseId.RENDER_RESPONSE)</code> on the JSF
<code>PartialViewContext</code>.</para>
<programlisting language="java">public class FileUploadBean {
public void listener(FileUploadEvent event) throws Exception{
FacesContext.getCurrentInstance().getPartialViewContext().processPartial(PhaseId.RENDER_RESPONSE);
ExternalContextHolder.getExternalContext().recordResponseComplete();
UploadedFile file = event.getUploadedFile();
// Do something with the file
}
}</programlisting>
<para>For more details refer to the
<link xl:href="http://www.jboss.org/richfaces/docs">RichFaces documentation</link>.</para>
</sect2>
</sect1>
<sect1 xml:id="spring-faces-security-taglib">

45
src/reference/spring-js.xml
View File

@@ -11,42 +11,23 @@
<sect1 xml:id="spring-js-introduction">
<title>Introduction</title>
<para>
Spring Javascript (spring-js) is a lightweight abstraction over common JavaScript toolkits such as Dojo.
It aims to provide a common client-side programming model for progressively enhancing a web page with rich widget behavior and Ajax remoting.
The <emphasis>spring-js-resources</emphasis> module is a legacy module that is no longer recommended for use
but is provided still as an optional module for backwards compatibility. Its original aim is to provide a
client-side programming model for progressively enhancing a web page with behavior and Ajax remoting.
</para>
<para>
Use of the Spring JS API is demonstrated in the the Spring MVC + Web Flow version of the Spring Travel reference application.
Use of the Spring JS API is demonstrated in the
<link xl:href="https://github.com/spring-projects/spring-webflow-samples">samples repository</link>.
</para>
</sect1>
<sect1 xml:id="spring-js-resource-servlet">
<title>Serving Javascript Resources</title>
<para>
Spring JS provides a generic <code>ResourceServlet</code> to serve web resources such as JavaScript and CSS files from jar files,
as well as the webapp root directory.
This servlet provides a convenient way to serve Spring.js files to your pages.
To deploy this servlet, declare the following in <code>web.xml</code>:
</para>
<programlisting language="xml"><![CDATA[
<!-- Serves static resource content from .jar files such as spring-js.jar -->
<servlet>
<servlet-name>Resource Servlet</servlet-name>
<servlet-class>org.springframework.js.resource.ResourceServlet</servlet-class>
</servlet>
<!-- Map all /resources requests to the Resource Servlet for handling -->
<servlet-mapping>
<servlet-name>Resource Servlet</servlet-name>
<url-pattern>/resources/*</url-pattern>
</servlet-mapping>]]>
</programlisting>
<para>
Note that starting with version 3.0.4, the Spring Framework includes
a replacement for the <code>ResourceServlet</code> (see the
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/mvc.html#mvc-static-resources">Spring Framework documentation</link>).
With the new &lt;mvc:resources&gt; element resource requests (.js, .css) are handled by the
<code>DispatcherSevlet</code> without the need for a separate <code>ResourceServlet</code>.
Here is the relevant portion of the Spring MVC configuration in
the mvc-booking sample:
The Spring Framework provides a mechanism for serving static resources.
See the
<link xl:href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-config-static-resources">Spring Framework documentation</link>).
With the new &lt;mvc:resources&gt; element resource requests (.js, .css) are handled by the<code>DispatcherSevlet</code>.
Here is example configuration in XML (Java config is also available):
</para>
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
@@ -77,12 +58,12 @@
</para>
<programlisting language="xml"><![CDATA[
<servlet>
<servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
<servlet-name>DispatcherServlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
<servlet-name>DispatcherServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
]]>
@@ -263,7 +244,7 @@
</para>
<programlisting language="xml"><![CDATA[
<bean id="tilesViewResolver" class="org.springframework.webflow.mvc.view.AjaxUrlBasedViewResolver">
<property name="viewClass" value="org.springframework.webflow.mvc.view.FlowAjaxTilesView"/>
<property name="viewClass" value="org.springframework.webflow.mvc.view.FlowAjaxTiles3View"/>
</bean>]]>
</programlisting>
<para>

15
src/reference/whatsnew.xml
View File

@@ -11,8 +11,19 @@
<sect1 xml:id="whatsnew-swf-250">
<title>Spring Web Flow 2.5</title>
<para>This release requires JDK 1.8 and Spring Framework 5.0.</para>
<!-- TODO -->
<para>
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
<link xl:href="https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-Spring-Framework-5.x">Spring Framework wiki</link>
for more details. The <link xl:href="https://github.com/spring-projects/spring-webflow-samples">samples repository</link>
has been upgraded to Spring Web Flow 2.5.
</para>
<para>
As of 2.5 there is no longer a <emphasis>spring-js</emphasis> module. The classes from that module
have been kept but moved to new packages in the <emphasis>spring-webflow</emphasis> module.
The <emphasis>spring-js-resources</emphasis> module is available as an optional module that
must be included explicitly.
</para>
</sect1>
<sect1 xml:id="whatsnew-swf-240">