Update reference with Java config examples

2014-03-31 15:03:11 -04:00
parent ecd213dc8f
commit 893df095c6
6 changed files with 296 additions and 43 deletions
--- a/src/reference/system-setup.xml
+++ b/src/reference/system-setup.xml
@@ -14,11 +14,14 @@
 			This chapter shows you how to setup the Web Flow system for use in any web environment.
 		</para>
 	</sect1>
-	<sect1 xml:id="system-config-schema">
-		<title>webflow-config.xsd</title>
+	<sect1 xml:id="system-config-options">
+		<title>Java Config and XML Namespace</title>
 		<para>
-			Web Flow provides a Spring schema that allows you to configure the system.
-			To use this schema, include it in one of your infrastructure-layer beans files:
+			Web Flow provides dedicated configuration support for both Java and
+			XML-based configuration.
+		</para>
+		<para>
+			To get started with XML based configuration declare the webflow config XML namespace:
 		</para>
 		<programlisting language="xml"><![CDATA[
 <beans xmlns="http://www.springframework.org/schema/beans"
@@ -26,14 +29,27 @@
       xmlns:webflow="http://www.springframework.org/schema/webflow-config"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
-           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+           http://www.springframework.org/schema/beans/spring-beans-4.0.xsd
           http://www.springframework.org/schema/webflow-config
-           http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.3.xsd">
+           http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.4.xsd">

    <!-- Setup Web Flow here -->

 </beans>]]>
 		</programlisting>
+		<para>
+			To get started with Java configuration extend
+			<classname>AbstractFlowConfiguration</classname> in an
+			<classname>@Configuration</classname> class:
+		</para>
+		<programlisting language="java"><![CDATA[
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class WebFlowConfig extends AbstractFlowConfiguration {
+
+}]]>
+		</programlisting>
 	</sect1>
 	<sect1 xml:id="system-config-basic">
 		<title>Basic system configuration</title>
@@ -43,21 +59,41 @@
 		<sect2 xml:id="basic-setup-flow-registry">
 			<title>FlowRegistry</title>
 			<para>
-				Register your flows in a <code>FlowRegistry</code>:
+				Register your flows in a <code>FlowRegistry</code> in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-registry id="flowRegistry">
    <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
 </webflow:flow-registry>]]>
 			</programlisting>
+			<para>
+				Register your flows in a <code>FlowRegistry</code> in Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowDefinitionRegistry flowRegistry() {
+    return getFlowDefinitionRegistryBuilder()
+        .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
+        .build();
+}]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="basic-setup-flow-executor">
 			<title>FlowExecutor</title>
 			<para>
-				Deploy a FlowExecutor, the central service for executing flows:
+				Deploy a FlowExecutor, the central service for executing flows in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-executor id="flowExecutor" />]]>
+			</programlisting>
+			<para>
+				Deploy a FlowExecutor, the central service for executing flows in Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowExecutor flowExecutor() {
+    return getFlowExecutorBuilder(flowRegistry()).build();
+}]]>
 			</programlisting>
 			<para>
 				See the Spring MVC and Spring Faces sections of this guide on how to integrate the Web Flow system with the MVC and JSF environment, respectively.
@@ -73,25 +109,48 @@
 			<title>Specifying flow locations</title>
 			<para>
 				Use the <code>location</code> element to specify paths to flow definitions to register.
-				By default, flows will be assigned registry identifiers equal to their filenames minus the file extension, unless a registry bath path is defined.
+				By default, flows will be assigned registry identifiers equal to their filenames minus
+				the file extension, unless a registry bath path is defined.
+			</para>
+			<para>
+				In XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />]]>
 			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+return getFlowDefinitionRegistryBuilder()
+        .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
+        .build();]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="flow-registry-location-id">
 			<title>Assigning custom flow identifiers</title>
 			<para>
-				Specify an id to assign a custom registry identifier to a flow:
+				Specify an id to assign a custom registry identifier to a flow in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" id="bookHotel" />]]>
 			</programlisting>
+			<para>
+				Specify an id to assign a custom registry identifier to a flow in Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+return getFlowDefinitionRegistryBuilder()
+        .addFlowLocation("/WEB-INF/flows/booking/booking.xml", "bookHotel")
+        .build();]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="flow-registry-location-attributes">
 			<title>Assigning flow meta-attributes</title>
 			<para>
-				Use the <code>flow-definition-attributes</code> element to assign custom meta-attributes to a registered flow:
+				Use the <code>flow-definition-attributes</code> element to assign custom meta-attributes to a registered flow.
+			</para>
+			<para>
+				In XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml">
@@ -100,15 +159,36 @@
    </webflow:flow-definition-attributes>
 </webflow:flow-location>]]>
 			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+Map<String, Object> attrs = ... ;
+
+return getFlowDefinitionRegistryBuilder()
+        .addFlowLocation("/WEB-INF/flows/booking/booking.xml", null, attrs)
+        .build();]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="flow-registry-patterns">
 			<title>Registering flows using a location pattern</title>
 			<para>
 				Use the <code>flow-location-patterns</code> element to register flows that match a specific resource location pattern:
 			</para>
+			<para>
+				In XML:
+			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-location-pattern value="/WEB-INF/flows/**/*-flow.xml" />]]>
 			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+return getFlowDefinitionRegistryBuilder()
+        .addFlowLocationPattern("/WEB-INF/flows/**/*-flow.xml")
+        .build();]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="flow-registry-base-path">
 			<title>Flow location base path</title>
@@ -117,10 +197,22 @@
 				All flow locations are then relative to the base path.
 				The base path can be a resource path such as '/WEB-INF' or a location on the classpath like 'classpath:org/springframework/webflow/samples'.
 			</para>
+			<para>
+				In XML:
+			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-registry id="flowRegistry" base-path="/WEB-INF">
    <webflow:flow-location path="/hotels/booking/booking.xml" />
 </webflow:flow-registry>]]>
+			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+return getFlowDefinitionRegistryBuilder()
+        .setBasePath("/WEB-INF")
+        .addFlowLocationPattern("/hotels/booking/booking.xml")
+        .build();]]>
 			</programlisting>
 			<para>
 				With a base path defined, the algorithm that assigns flow identifiers changes slightly.
@@ -142,12 +234,21 @@
 			<para>
 				Location patterns are particularly powerful when combined with a registry base path.
 				Instead of the flow identifiers becoming '*-flow', they will be based on the directory path.
-				For example:
+				For example in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-registry id="flowRegistry" base-path="/WEB-INF">
    <webflow:flow-location-pattern value="/**/*-flow.xml" />
 </webflow:flow-registry>]]>
+			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+return getFlowDefinitionRegistryBuilder()
+        .setBasePath("/WEB-INF")
+        .addFlowLocationPattern("/**/*-flow.xml")
+        .build();]]>
 			</programlisting>
 			<para>
 				In the above example, suppose you had flows located in <code>/user/login</code>, <code>/user/registration</code>, <code>/hotels/booking</code>, and <code>/flights/booking</code> directories within <code>WEB-INF</code>,
@@ -160,6 +261,9 @@
 				Use the <code>parent</code> attribute to link two flow registries together in a hierarchy.
 				When the child registry is queried, if it cannot find the requested flow it will delegate to its parent.
 			</para>
+			<para>
+				In XML:
+			</para>
 			<programlisting language="xml"><![CDATA[
 <!-- my-system-config.xml -->
 <webflow:flow-registry id="flowRegistry" parent="sharedFlowRegistry">
@@ -171,6 +275,36 @@
    <!-- Global flows shared by several applications -->
 </webflow:flow-registry>]]>
 			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+@Configuration
+public class WebFlowConfig extends AbstractFlowConfiguration {
+
+    @Autowired
+    private SharedConfig sharedConfig;
+
+    @Bean
+    public FlowDefinitionRegistry flowRegistry() {
+        return getFlowDefinitionRegistryBuilder()
+                .setParent(this.sharedConfig.sharedFlowRegistry())
+                .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
+                .build();
+    }
+}
+
+@Configuration
+public class SharedConfig extends AbstractFlowConfiguration {
+
+    @Bean
+    public FlowDefinitionRegistry sharedFlowRegistry() {
+        return getFlowDefinitionRegistryBuilder()
+                .addFlowLocation("/WEB-INF/flows/shared.xml")
+                .build();
+    }
+}]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="flow-registry-builder-services">
 			<title>Configuring custom FlowBuilder services</title>
@@ -179,16 +313,34 @@
 				If no flow-builder-services tag is specified, the default service implementations are used.
 				When the tag is defined, you only need to reference the services you want to customize.
 			</para>
+			<para>In XML:</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-registry id="flowRegistry" flow-builder-services="flowBuilderServices">
    <webflow:flow-location path="/WEB-INF/flows/booking/booking.xml" />
 </webflow:flow-registry>

 <webflow:flow-builder-services id="flowBuilderServices" />]]>
+			</programlisting>
+			<para>In Java:</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowDefinitionRegistry flowRegistry() {
+	return getFlowDefinitionRegistryBuilder(flowBuilderServices())
+            .addFlowLocation("/WEB-INF/flows/booking/booking.xml")
+            .build();
+}
+
+@Bean
+public FlowBuilderServices flowBuilderServices() {
+    return getFlowBuilderServicesBuilder().build();
+}]]>
 			</programlisting>
 			<para>
 				The configurable services are the <code>conversion-service</code>, <code>expression-parser</code>, and <code>view-factory-creator</code>.
-				These services are configured by referencing custom beans you define.  For example:
+				These services are configured by referencing custom beans you define.
+			</para>
+			<para>
+				For example in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-builder-services id="flowBuilderServices"
@@ -199,6 +351,32 @@
 <bean id="conversionService" class="..." />
 <bean id="expressionParser" class="..." />
 <bean id="viewFactoryCreator" class="..." />]]>
+			</programlisting>
+			<para>In Java:</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowBuilderServices flowBuilderServices() {
+    return getFlowBuilderServicesBuilder()
+            .setConversionService(conversionService())
+            .setExpressionParser(expressionParser)
+            .setViewFactoryCreator(mvcViewFactoryCreator())
+            .build();
+}
+
+@Bean
+public ConversionService conversionService() {
+    // ...
+}
+
+@Bean
+public ExpressionParser expressionParser() {
+    // ...
+}
+
+@Bean
+public ViewFactoryCreator viewFactoryCreator() {
+    // ...
+}]]>
 			</programlisting>
 			<sect3 xml:id="builder-service-conversion">
 				<title>conversion-service</title>
@@ -245,7 +423,8 @@
 		<sect2 xml:id="flow-executor-execution-listeners">
 			<title>Attaching flow execution listeners</title>
 			<para>
-				Use the <code>flow-execution-listeners</code> element to register listeners that observe the lifecycle of flow executions:
+				Use the <code>flow-execution-listeners</code> element to register listeners that observe the lifecycle
+				of flow executions. For example in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-execution-listeners>
@@ -254,21 +433,57 @@
 </webflow:flow-execution-listeners>]]>
 			</programlisting>
 			<para>
-				You may also configure a listener to observe only certain flows:
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowExecutor flowExecutor() {
+    return getFlowExecutorBuilder(flowRegistry())
+            .addFlowExecutionListener(securityListener())
+            .addFlowExecutionListener(persistenceListener())
+            .build();
+}]]>
+			</programlisting>
+			<para>
+				You may also configure a listener to observe only certain flows. For example in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:listener ref="securityListener" criteria="securedFlow1,securedFlow2"/>]]>
 			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowExecutor flowExecutor() {
+    return getFlowExecutorBuilder(flowRegistry())
+            .addFlowExecutionListener(securityListener(), "securedFlow1,securedFlow2")
+            .build();
+}]]>
+			</programlisting>
 		</sect2>
 		<sect2 xml:id="tuning-flow-execution-repository">
 			<title>Tuning FlowExecution persistence</title>
 			<para>
-				Use the <code>flow-execution-repository</code> element to tune flow execution persistence settings:
+				Use the <code>flow-execution-repository</code> element to tune flow execution persistence settings.
+				For example in XML:
 			</para>
 			<programlisting language="xml"><![CDATA[
 <webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry">
    <webflow:flow-execution-repository max-executions="5" max-execution-snapshots="30" />
 </webflow:flow-executor>]]>
+			</programlisting>
+			<para>
+				In Java:
+			</para>
+			<programlisting language="java"><![CDATA[
+@Bean
+public FlowExecutor flowExecutor() {
+    return getFlowExecutorBuilder(flowRegistry())
+            .setMaxFlowExecutions(5)
+            .setMaxFlowExecutionSnapshots(30)
+            .build();
+}]]>
 			</programlisting>
 			<sect3 xml:id="repository-max-executions">
 				<title>max-executions</title>