From 956211b44d07eb7c07dfeff5d59615c0b863887c Mon Sep 17 00:00:00 2001
From: Keith Donald <kdonald@vmware.com>
Date: Wed, 5 Mar 2008 17:47:03 +0000
Subject: [PATCH] docs

---
 .../config/spring-webflow-config-2.0.xsd      | 126 ++++++++----------
 1 file changed, 59 insertions(+), 67 deletions(-)

diff --git a/spring-webflow/src/main/java/org/springframework/webflow/config/spring-webflow-config-2.0.xsd b/spring-webflow/src/main/java/org/springframework/webflow/config/spring-webflow-config-2.0.xsd
index afd58abc..576cf2d8 100644
--- a/spring-webflow/src/main/java/org/springframework/webflow/config/spring-webflow-config-2.0.xsd
+++ b/spring-webflow/src/main/java/org/springframework/webflow/config/spring-webflow-config-2.0.xsd
@@ -13,7 +13,7 @@
 Spring Web Flow Configuration Schema
 Authors: Keith Donald, Ben Hale, Jeremy Grelle
 <br>
-Provides an easy way to configure a flow executor and an XML flow definition registry.
+A XML-based DSL for configuring the Spring Web Flow 2.0 system.
 ]]>
 		</xsd:documentation>
 	</xsd:annotation>
@@ -24,15 +24,12 @@ Provides an easy way to configure a flow executor and an XML flow definition reg
 		<xsd:annotation>
 			<xsd:documentation>
 				<![CDATA[
-Deploys a flow definition registry.  A flow definition registry contains a set of flow definitions.
-A flow definition is typically built from externalized resource location such as a .xml file.
+Deploys a registry of flow definitions.  A flow registry is used by a flow executor to locate flows to execute.
 <br>
 Each flow definition registered in this registry is assigned a unique identifier. By default,
 this identifier is the name of the externalized resource minus its file extension.  For example,
 a registry containing flow definitions built from the files "orderitem-flow.xml" and "shipping-flow.xml"
 would index those definitions by "orderitem-flow" and "shipping-flow" by default.
-<br>
-A flow registry is used by a flow executor at runtime to launch new executions of flow definitions.
 ]]>
 			</xsd:documentation>
 		</xsd:annotation>
@@ -44,16 +41,15 @@ A flow registry is used by a flow executor at runtime to launch new executions o
 							<xsd:annotation>
 								<xsd:documentation>
 									<![CDATA[
-Specifies a path to a externalized flow definition resource.  The flow definition built from this
-resource will be registered in this registry.
+Registers a flow defined in an external resource such as a .xml file in this registry.
 <br>
-Individual paths such as:
+Supports individual resource paths such as:
 <pre>
-	/WEB-INF/booking.xml
+	/WEB-INF/flows/booking/booking.xml
 </pre>
-... are supported as well as wildcard paths such as:
+... as well as wildcard resource paths such as:
 <pre>
-	/WEB-INF/flows/**/*-flow.xml
+	/WEB-INF/flows/*/*.xml
 </pre>
 ]]>
 								</xsd:documentation>
@@ -63,7 +59,7 @@ Individual paths such as:
 							<xsd:annotation>
 								<xsd:documentation>
 									<![CDATA[
-Specifies a flow builder implementation to register in the registry.
+Registers a custom FlowBuilder implementation in this registry.
 ]]>
 								</xsd:documentation>
 							</xsd:annotation>
@@ -73,7 +69,8 @@ Specifies a flow builder implementation to register in the registry.
 						<xsd:annotation>
 							<xsd:documentation>
 								<![CDATA[
-The idref of the flow builder services instance this flow definition registry should use.
+A refernence to a FlowBuilderServices implementation defining custom services needed to build the flows registered in this registry.
+Optional.  For use when custom builder services are required.
 ]]>
 							</xsd:documentation>
 						</xsd:annotation>
@@ -89,7 +86,7 @@ The idref of the flow builder services instance this flow definition registry sh
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-Attributes to assign to the flow definition that may influence flow execution.
+Meta-attributes to assign to the flow definition.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -99,10 +96,9 @@ Attributes to assign to the flow definition that may influence flow execution.
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The id to the externalized flow definition resource. This only needs to be populated for explict declaration of flow
-identifiers.  If not populated this id of the flow is equal to the filename of the underlying definition resource, minus
-the filename extension.  This value cannot be set if an ANT-style path expression that matches multiple resources is
-used in path attribute. 
+The id assign the flow definition in this registry.  Optional.
+Specify when you wish to provide a custom flow definition identifier.
+When specified, the id must be unique among all flows in this registry.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>
@@ -111,7 +107,7 @@ used in path attribute.
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The path to the externalized flow definition resource. May be a path to a single resource or a ANT-style path expression
+The resource path to the externalized flow definition resource. May be a path to a single resource or a ANT-style path expression
 that matches multiple resources.
 ]]>
 				</xsd:documentation>
@@ -125,7 +121,7 @@ that matches multiple resources.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-Attributes to assign to the flow definition that may influence flow execution.
+Attributes to assign to the flow definition.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -135,7 +131,9 @@ Attributes to assign to the flow definition that may influence flow execution.
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The id to the externalized flow definition built by this builder.
+The id assign the flow definition in this registry.  Optional.
+Specify when you wish to provide a custom flow definition identifier.
+When specified, the id must be unique among all flows in this registry.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>
@@ -144,7 +142,7 @@ The id to the externalized flow definition built by this builder.
 			<xsd:annotation>
 				<xsd:documentation>
 				<![CDATA[
-The fully qualified class name of the flow builder implementation.
+The fully qualified class name of the FlowBuilder implementation.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>
@@ -155,10 +153,9 @@ The fully qualified class name of the flow builder implementation.
 		<xsd:annotation>
 			<xsd:documentation>
 				<![CDATA[
-Deploys a flow executor.  A flow executor executes flow definitions.  More specifically, an executor
-is responsible for launching new flow executions as well as resuming paused flow executions.
-A flow execution that spans more than one request is said to have 'paused' and is stored in
-an execution repository.
+Deploys a flow executor.  A FlowExecutor executes flow definitions and acts as the entry-point into the Web Flow system.
+A flow executor launches new flow executions and resumes paused flow executions.
+Paused flow executions are stored between requests in a FlowExecutionRepository.
 ]]>
 			</xsd:documentation>
 		</xsd:annotation>
@@ -170,8 +167,8 @@ an execution repository.
 							<xsd:annotation>
 								<xsd:documentation>
 									<![CDATA[
-Explicit repository configuration for this executor.  This element is used if configuration needs
-to be more fine grained than the repositoryType attribute on executor.
+Configures the type of FlowExecutionRepository that should be used by this executor.  Optional.
+Specify when you want to override the default repository implementation.
 ]]>
 								</xsd:documentation>
 							</xsd:annotation>
@@ -180,8 +177,8 @@ to be more fine grained than the repositoryType attribute on executor.
 							<xsd:annotation>
 								<xsd:documentation>
 									<![CDATA[
-Execution attributes to associate with new flow executions launched by this executor.
-These attributes may influence execution behavior.
+Meta attributes to assign new flow executions launched by this executor.  These attributes will be associated with all flow executions, 
+regardless of their underlying flow definition. Such attributes may influence flow execution behavior at runtime.
 ]]>
 								</xsd:documentation>
 							</xsd:annotation>
@@ -190,7 +187,7 @@ These attributes may influence execution behavior.
 							<xsd:annotation>
 								<xsd:documentation>
 									<![CDATA[
-The listeners eligible for observing the lifecycle of executions launched by this executor.
+Registers listeners that observe the lifecycle of flow executions launched by this executor.
 ]]>
 								</xsd:documentation>
 							</xsd:annotation>
@@ -200,7 +197,8 @@ The listeners eligible for observing the lifecycle of executions launched by thi
 						<xsd:annotation>
 							<xsd:documentation>
 								<![CDATA[
-The idref to the registry this executor will use to locate flow definitions for execution.
+A reference to the FlowRegistry bean containing the flows eligible for execution by this executor.
+The default value 'flowRegistry'.
 ]]>
 							</xsd:documentation>
 						</xsd:annotation>
@@ -214,7 +212,8 @@ The idref to the registry this executor will use to locate flow definitions for
 		<xsd:annotation>
 			<xsd:documentation>
 				<![CDATA[
-Allows access to the Spring Web Flow scopes (request, flash, flow, conversation) from a Spring ApplicationContext.
+Enables the Spring Web Flow bean scopes of 'request', 'flash', 'flow', and 'conversation'.
+With this tag, Spring bean can be placed in the Web Flow scopes.
 ]]>
 			</xsd:documentation>
 		</xsd:annotation>
@@ -224,8 +223,9 @@ Allows access to the Spring Web Flow scopes (request, flash, flow, conversation)
 		<xsd:annotation>
 			<xsd:documentation>
 				<![CDATA[
-Deploys the flow builder services, including the ViewFactoryCreator, ExpressionParser, and ConversionService to
-be used by a flow definition registry.
+Registers custom implementations of services needed to build flow definitions.
+With this tag, you may configure a custom ConversionService, ExpressionParser, ViewFactoryCreator, and FlowArtifactFactory implementation.
+This tag is only needed when you wish to plugin custom implementations.
 ]]>	
 			</xsd:documentation>
 		</xsd:annotation>
@@ -236,8 +236,7 @@ be used by a flow definition registry.
 						<xsd:annotation>
 							<xsd:documentation>
 								<![CDATA[
-The idref of the expression parser instance that should be used.  If not provided, the default OGNL expression parser 
-will be used.
+The custom ExpressionParser implementation to use.
 ]]>
 							</xsd:documentation>
 						</xsd:annotation>
@@ -246,8 +245,7 @@ will be used.
 						<xsd:annotation>
 							<xsd:documentation>
 								<![CDATA[
-The idref of the view factory creator that should be used.  The view factory creator is specific to the view technology
-being used.  If not provided, the default Spring MVC view factory creator  will be used.
+The custom ViewFactoryCreator implementation to use.
 ]]>
 							</xsd:documentation>
 						</xsd:annotation>
@@ -256,7 +254,7 @@ being used.  If not provided, the default Spring MVC view factory creator  will
 						<xsd:annotation>
 							<xsd:documentation>
 								<![CDATA[
-The idref of the conversion service that should be used.  If not provided, the default conversion service will be used.
+The custom ConversionService implementation to use.
 ]]>
 							</xsd:documentation>
 						</xsd:annotation>
@@ -271,8 +269,8 @@ The idref of the conversion service that should be used.  If not provided, the d
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The type of flow execution repository to use.  The repository is responsible for managing flow execution 
-persistence between requests.
+The type of flow execution repository to use.
+A FlowExecutionRepository manages flow execution persistence between requests.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>			
@@ -281,8 +279,8 @@ persistence between requests.
 			<xsd:annotation>
 				<xsd:documentation>
 				<![CDATA[
-The maximum number of concurrent conversations allowed by this repository.  It is illegal to set this
-attribute if you are also setting the 'conversation-manager' attribute.
+The maximum number of concurrent conversations allowed by this repository.  The default is 5.
+Do not set this attribute if you are also setting the 'conversation-manager' attribute.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>
@@ -291,8 +289,7 @@ attribute if you are also setting the 'conversation-manager' attribute.
 			<xsd:annotation>
 				<xsd:documentation>
 				<![CDATA[
-The maximum number of flow execution continuations (snapshots) allowed by this repository per conversation.
-This attribute is only relevant when the repository type is 'continuation'.
+The maximum number of flow execution continuations (snapshots) allowed by this repository per conversation.  The default is 30.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>
@@ -301,8 +298,8 @@ This attribute is only relevant when the repository type is 'continuation'.
 			<xsd:annotation>
 				<xsd:documentation>
 				<![CDATA[
-The idref of the conversation manager this repository should use.  Setting this attribute 
-allows full control over the conversation manager implementation and configuration.
+The custom ConversationManager implementation to use with the FlowExecutionRepository.
+Setting this attribute allows full control over the conversation manager implementation and configuration.
 When used, any value for the 'max-conversations' attribute is ignored.
 ]]>
 				</xsd:documentation>
@@ -317,7 +314,7 @@ When used, any value for the 'max-conversations' attribute is ignored.
 					<xsd:documentation>
 						<![CDATA[
 The continuation repository type.  Use this to snapshot flow execution state server-side to support use 
-of the browser back button.
+of the browser back button.  This is the default if not specified.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -326,8 +323,7 @@ of the browser back button.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-The simple repository type.  Use of this strategy incurs minimal storage overhead but explicitly prevents 
-resubmits using the browser back button.
+The simple repository type.  Use of this strategy incurs minimal storage overhead but explicitly prevents resubmits using the browser back button.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -336,8 +332,8 @@ resubmits using the browser back button.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-The client continuation repository type.  Use this to snapshot flow execution state client-side to support use of the browser 
-back button in a stateless server environment.
+The client continuation repository type.
+Use this to snapshot flow execution state client-side to support use of the browser back button in a stateless server environment.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -346,8 +342,8 @@ back button in a stateless server environment.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-The "single key" repository type.  Use of this strategy assigns a single key per flow execution that remains 
-constant throughout the life of the execution.
+The "single key" repository type.
+Use of this strategy assigns a single key per flow execution that remains constant throughout the life of the execution.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -361,8 +357,8 @@ constant throughout the life of the execution.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-Deploys a single flow execution listener that will observe the execution lifecycle of one or more
-flow definitions.  The flow definitions this listener applies to may be restricted by specifying criteria.
+Registers a listener to observe the execution lifecycle of one or more flows.
+The flow definitions this listener observes may be restricted by specifying listener criteria.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -375,7 +371,7 @@ flow definitions.  The flow definitions this listener applies to may be restrict
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The idref to your flow execution listener.
+A reference to the flow execution listener implementation to register.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>
@@ -384,7 +380,7 @@ The idref to your flow execution listener.
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The flow definitions your listener should apply to, delimited by commas or '*' for "all".
+The criteria that determines the flow definitions your listener should observe, delimited by commas or '*' for "all".
 Example: 'flow1,flow2,flow3'.
 ]]>
 				</xsd:documentation>
@@ -398,9 +394,7 @@ Example: 'flow1,flow2,flow3'.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-Sets the 'alwaysRedirectOnPause' execution attribute value.  'alwaysRedirectOnPause' allows 
-control over whether each time a flow execution pauses a browser redirect is performed.  If
-not specified the default value is 'true' unless explicitly set otherwise.
+Determines if flow executions always redirect after they pause.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -409,8 +403,7 @@ not specified the default value is 'true' unless explicitly set otherwise.
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-A single attribute describing an element.  Attributes have string keys and object values.
-An attribute's type may be specified using the 'type' attribute.
+A single flow execution meta attribute.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -436,8 +429,7 @@ true = always redirect on pause; false = do not, only redirect when explicitly i
 				<xsd:annotation>
 					<xsd:documentation>
 						<![CDATA[
-A single attribute describing an element.  Attributes have string keys and object values.
-An attribute's type may be specified using the 'type' attribute.
+A single flow definition meta attribute.
 ]]>
 					</xsd:documentation>
 				</xsd:annotation>
@@ -468,7 +460,7 @@ The attribute's type, used to perform a from-string type conversion if specified
 			<xsd:annotation>
 				<xsd:documentation>
 					<![CDATA[
-The attribute value, subject to type conversion if the 'type' attribute is defined.
+The attribute value, subject to a type conversion if the 'type' attribute is defined.
 ]]>
 				</xsd:documentation>
 			</xsd:annotation>