From: Mathieu Baudier <mbaudier@argeo.org>
Date: Fri, 15 Jan 2010 12:01:39 +0000 (+0000)
Subject: Flow XSD documentation.
X-Git-Tag: argeo-slc-2.1.7~1464
X-Git-Url: http://git.argeo.org/?a=commitdiff_plain;h=44d72c1a645ca69e28ad03d46367cd4a9dde99bd;p=gpl%2Fargeo-slc.git

Flow XSD documentation.

git-svn-id: https://svn.argeo.org/slc/trunk@3290 4cfe0d0a-d680-48aa-b62c-e0a02a3f76cc
---

diff --git a/runtime/org.argeo.slc.core/src/main/resources/org/argeo/slc/core/execution/xml/slc-flow-0.12.xsd b/runtime/org.argeo.slc.core/src/main/resources/org/argeo/slc/core/execution/xml/slc-flow-0.12.xsd
index 51c237177..439528e0f 100644
--- a/runtime/org.argeo.slc.core/src/main/resources/org/argeo/slc/core/execution/xml/slc-flow-0.12.xsd
+++ b/runtime/org.argeo.slc.core/src/main/resources/org/argeo/slc/core/execution/xml/slc-flow-0.12.xsd
@@ -6,14 +6,36 @@
 
 	<xsd:import namespace="http://www.springframework.org/schema/beans" />
 
+	<xsd:annotation>
+		<xsd:documentation><![CDATA[
+	SLC Flow Schema, version 0.12
+	Authors: Mathieu Baudier
+	
+	This simplifies the definition of SLC flows and their integration with 
+	regular Spring beans.
+		]]></xsd:documentation>
+	</xsd:annotation>
+
 	<xsd:element name="flow">
+		<xsd:annotation>
+			<xsd:documentation><![CDATA[
+	Adds an SLC execution flow, using the default implementation.
+			]]></xsd:documentation>
+		</xsd:annotation>
 		<xsd:complexType>
 			<xsd:complexContent>
 				<xsd:extension base="beans:identifiedType">
 					<xsd:sequence>
 						<xsd:sequence>
 							<xsd:element name="arg" minOccurs="0" maxOccurs="unbounded"
-								type="flow:argType" />
+								type="flow:argType">
+								<xsd:annotation>
+									<xsd:documentation><![CDATA[
+	Parameter for an execution flow which will override at instantiation the 
+	value of the parameter already defined as default value or in a parent bean.
+									]]></xsd:documentation>
+								</xsd:annotation>
+							</xsd:element>
 						</xsd:sequence>
 						<xsd:sequence>
 							<xsd:choice minOccurs="0" maxOccurs="unbounded">
@@ -26,26 +48,70 @@
 							-->
 						</xsd:sequence>
 					</xsd:sequence>
-					<xsd:attribute name="path" type="xsd:string" />
-					<xsd:attribute name="spec" type="xsd:string" />
-					<xsd:attribute name="parent" type="xsd:string" />
+					<xsd:attribute name="path" type="xsd:string">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+	The hierarchical path under which to register this flow.
+							]]></xsd:documentation>
+						</xsd:annotation>
+					</xsd:attribute>
+					<xsd:attribute name="spec" type="xsd:string">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+	A reference to the related specification bean.
+							]]></xsd:documentation>
+						</xsd:annotation>
+					</xsd:attribute>
+					<xsd:attribute name="parent" type="xsd:string">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+	The parent bean definition (in Spring sense).
+							]]></xsd:documentation>
+						</xsd:annotation>
+					</xsd:attribute>
 					<xsd:attribute name="abstract" type="xsd:boolean"
-						default="false" />
+						default="false">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+	Whether this flow is abstract (in Spring sense).
+							]]></xsd:documentation>
+						</xsd:annotation>
+					</xsd:attribute>
 				</xsd:extension>
 			</xsd:complexContent>
 		</xsd:complexType>
 	</xsd:element>
 
 	<xsd:element name="spec">
+		<xsd:annotation>
+			<xsd:documentation><![CDATA[
+	SLC flow specifications, defining the parameters and variables
+	which can be used in related flows, along with their default values and 
+	various constraints.
+			]]></xsd:documentation>
+		</xsd:annotation>
 		<xsd:complexType>
 			<xsd:complexContent>
 				<xsd:extension base="beans:identifiedType">
 					<xsd:sequence>
 						<xsd:choice minOccurs="0" maxOccurs="unbounded">
 							<xsd:element name="primitive" type="flow:primitiveSpecAttributeType"
-								minOccurs="0" maxOccurs="unbounded" />
+								minOccurs="0" maxOccurs="unbounded">
+								<xsd:annotation>
+									<xsd:documentation><![CDATA[
+	A primitive specification attribute, that is, a plain standard value
+	and not a reference to an object.
+									]]></xsd:documentation>
+								</xsd:annotation>
+							</xsd:element>
 							<xsd:element name="ref" type="flow:refSpecAttributeType"
-								minOccurs="0" maxOccurs="unbounded" />
+								minOccurs="0" maxOccurs="unbounded">
+								<xsd:annotation>
+									<xsd:documentation><![CDATA[
+	A reference specification attribute, that is, a reference to another object.
+									]]></xsd:documentation>
+								</xsd:annotation>
+							</xsd:element>
 						</xsd:choice>
 					</xsd:sequence>
 				</xsd:extension>
@@ -56,28 +122,77 @@
 	<xsd:complexType name="specAttributeType">
 		<xsd:choice>
 			<xsd:element name="value" minOccurs="0" maxOccurs="1">
+				<xsd:annotation>
+					<xsd:documentation><![CDATA[
+	The default value of the attribute as an inner bean.
+					]]></xsd:documentation>
+				</xsd:annotation>
 				<xsd:complexType>
-					<xsd:choice>
-						<xsd:any minOccurs="1" maxOccurs="1" />
+					<xsd:choice minOccurs="1" maxOccurs="1">
+						<xsd:element ref="beans:bean" />
+						<xsd:element ref="beans:ref" />
 					</xsd:choice>
 				</xsd:complexType>
 			</xsd:element>
 		</xsd:choice>
-		<xsd:attribute name="name" use="required" type="xsd:string" />
-		<xsd:attribute name="value" use="optional" type="xsd:string" />
-		<xsd:attribute name="ref" use="optional" type="xsd:string" />
+		<xsd:attribute name="name" use="required" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The name of the attribute, under which in can then be referenced.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
+		<xsd:attribute name="value" use="optional" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The default value of the attribute.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
+		<xsd:attribute name="ref" use="optional" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The default value of the attribute as a reference to another bean.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
 		<xsd:attribute name="isParameter" use="optional" type="xsd:boolean"
-			default="false" />
+			default="false">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	Whether the attribute is a parameter, that is, it has to be set at 
+	instantiation but can be modified afterwards for objects of scope execution.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
 		<xsd:attribute name="isFrozen" use="optional" type="xsd:boolean"
-			default="false" />
+			default="false">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	Whether the attribute is frozen, that is, it cannot be modified at runtime.
+	A frozen attribute has to be a parameter.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
 		<xsd:attribute name="isHidden" use="optional" type="xsd:boolean"
-			default="false" />
+			default="false">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	Whether the attribute is hidden, that is, it should not be displayed in UIs.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
 	</xsd:complexType>
 
 	<xsd:complexType name="primitiveSpecAttributeType">
 		<xsd:complexContent>
 			<xsd:extension base="flow:specAttributeType">
 				<xsd:attribute name="type" default="string">
+					<xsd:annotation>
+						<xsd:documentation><![CDATA[
+	The type of the primitive specification attribute.
+						]]></xsd:documentation>
+					</xsd:annotation>
 					<xsd:simpleType>
 						<xsd:restriction base="xsd:string">
 							<xsd:enumeration value="string" />
@@ -98,22 +213,53 @@
 			<xsd:extension base="flow:specAttributeType">
 				<xsd:choice>
 					<xsd:element name="choices" minOccurs="0" maxOccurs="1">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+	Possible values to chose from, if ommitted, all the beans in the 
+	application context which implement the provided targetClass will 
+	be considered.
+							]]></xsd:documentation>
+						</xsd:annotation>
 						<xsd:complexType>
 							<xsd:choice>
 								<xsd:element name="choice" minOccurs="0" maxOccurs="unbounded"
-									type="flow:refChoiceType" />
+									type="flow:refChoiceType">
+									<xsd:annotation>
+										<xsd:documentation><![CDATA[
+	A choice for a reference specification attribute.
+										]]></xsd:documentation>
+									</xsd:annotation>
+								</xsd:element>
 							</xsd:choice>
 						</xsd:complexType>
 					</xsd:element>
 				</xsd:choice>
-				<xsd:attribute name="targetClass" use="required" type="xsd:string" />
+				<xsd:attribute name="targetClass" use="required" type="xsd:string">
+					<xsd:annotation>
+						<xsd:documentation><![CDATA[
+	The class that has to be implemented by the underlying object.
+					]]></xsd:documentation>
+					</xsd:annotation>
+				</xsd:attribute>
 			</xsd:extension>
 		</xsd:complexContent>
 	</xsd:complexType>
 
 	<xsd:complexType name="refChoiceType">
-		<xsd:attribute name="name" use="required" type="xsd:string" />
-		<xsd:attribute name="description" use="optional" type="xsd:string" />
+		<xsd:attribute name="name" use="required" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The name of the related bean.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
+		<xsd:attribute name="description" use="optional" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	A human readable description of this choice.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
 	</xsd:complexType>
 
 	<xsd:complexType name="argType">
@@ -121,18 +267,62 @@
 			<xsd:element ref="beans:bean" />
 			<xsd:element ref="beans:ref" />
 		</xsd:choice>
-		<xsd:attribute name="name" use="required" type="xsd:string" />
-		<xsd:attribute name="value" type="xsd:string" />
-		<xsd:attribute name="ref" type="xsd:string" />
+		<xsd:attribute name="name" use="required" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The name of the related parameter.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
+		<xsd:attribute name="value" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The plain value of the related parameter.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
+		<xsd:attribute name="ref" type="xsd:string">
+			<xsd:annotation>
+				<xsd:documentation><![CDATA[
+	The value of the related parameter as a reference to a bean.
+				]]></xsd:documentation>
+			</xsd:annotation>
+		</xsd:attribute>
 	</xsd:complexType>
 
-	<xsd:attribute name="as-flow" type="xsd:string" />
+	<xsd:attribute name="as-flow" type="xsd:string">
+		<xsd:annotation>
+			<xsd:documentation><![CDATA[
+	If decorating an executable bean, it will generate an implicit SLC 
+	execution flow with the provided value as name.
+			]]></xsd:documentation>
+		</xsd:annotation>
+	</xsd:attribute>
 
 	<xsd:element name="param">
+		<xsd:annotation>
+			<xsd:documentation><![CDATA[
+	If within a property tag of a bean, it will set the value of this property
+	 with a reference to a parameter.
+			]]></xsd:documentation>
+		</xsd:annotation>
 		<xsd:complexType>
-			<xsd:attribute name="name" type="xsd:string" use="required" />
+			<xsd:attribute name="name" type="xsd:string" use="required">
+				<xsd:annotation>
+					<xsd:documentation><![CDATA[
+	The name of the related parameter.
+					]]></xsd:documentation>
+				</xsd:annotation>
+			</xsd:attribute>
 			<xsd:attribute name="instantiationManager" type="xsd:string"
-				use="optional" default="instantiationManager" />
+				use="optional" default="instantiationManager">
+				<xsd:annotation>
+					<xsd:documentation><![CDATA[
+	A reference to the instantiation manager to use instead of the default one
+	(expert usage).
+					]]></xsd:documentation>
+				</xsd:annotation>
+			</xsd:attribute>
 		</xsd:complexType>
 	</xsd:element>