INT-2473 - Update Doc for Xslt Transformers

INT-2473 Document XSD for xslt-transformer

* convert spaces to tabs in XsltPayloadTransformerParser
* Add JavaDoc to ResultTransformer

INT-2473 - Code/Doc Review

* Add documentation for *SourceFactories*
* Add links
* Rephrase section on *ResultTransformers*

Minor polish

spring-integration-xml/src/main/java/org/springframework/integration/xml/config/XsltPayloadTransformerParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2010 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -61,10 +61,10 @@ public class XsltPayloadTransformerParser extends AbstractTransformerParser {
 			builder.addConstructorArgReference(xslTemplates);
 		}
 		XmlNamespaceUtils.configureResultFactory(builder, resultType, resultFactory);
-        boolean resultFactorySpecified = StringUtils.hasText(resultFactory) || StringUtils.hasText(resultType);
-        if(resultFactorySpecified){
-            builder.addPropertyValue("alwaysUseResultFactory", true);
-        }
+		boolean resultFactorySpecified = StringUtils.hasText(resultFactory) || StringUtils.hasText(resultType);
+		if(resultFactorySpecified){
+			builder.addPropertyValue("alwaysUseResultFactory", true);
+		}
 		if (StringUtils.hasText(resultTransformer)) {
 			builder.addConstructorArgReference(resultTransformer);
 		}
@@ -93,7 +93,7 @@ public class XsltPayloadTransformerParser extends AbstractTransformerParser {
 			builder.addPropertyValue("xslParameterMappings", xslParameterMappings);
 		}
 
-       IntegrationNamespaceUtils.setReferenceIfAttributeDefined(builder, element, "source-factory");
+		IntegrationNamespaceUtils.setReferenceIfAttributeDefined(builder, element, "source-factory");
 
 	}
 

spring-integration-xml/src/main/java/org/springframework/integration/xml/transformer/ResultTransformer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2010 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -19,7 +19,12 @@ package org.springframework.integration.xml.transformer;
 import javax.xml.transform.Result;
 
 /**
+ * Implementations of this class allow for the transformation of {@link Result}
+ * objects to other formats.
+ *
  * @author Jonas Partner
+ * @author Gunnar Hillert
+ *
  */
 public interface ResultTransformer {
 

spring-integration-xml/src/main/resources/org/springframework/integration/xml/config/spring-integration-xml-2.2.xsd

@@ -108,12 +108,59 @@
 			<xsd:complexContent>
 				<xsd:extension base="inputOutputEndpoint">
 					<xsd:sequence>
-						<xsd:element name="xslt-param" type="paramType" minOccurs="0" maxOccurs="unbounded"/>
+						<xsd:element name="xslt-param" type="paramType" minOccurs="0" maxOccurs="unbounded">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								Allows to configure individual Xslt parameters.
+								There the 'expression' and 'value' attribute are
+								available. The expression attribute should be
+								any valid SpEL expression with the message being
+								the root object of the expression evaluation
+								context.
+
+								The value attribute, just like any value in Spring
+								beans, allows you to specify simple static values.
+
+								You can also use property placeholders (e.g.,
+								${some.value}).
+							]]></xsd:documentation>
+						</xsd:annotation>
+						</xsd:element>
 					</xsd:sequence>
-					<xsd:attribute name="xslt-param-headers" type="xsd:string" use="optional"/>
-					<xsd:attribute name="xsl-resource" type="xsd:string" use="optional"/>
+					<xsd:attribute name="xslt-param-headers" type="xsd:string" use="optional">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								If message header names match 1:1 to parameter
+								names, you can use this attribute to make
+								the parameters available.
+
+								The use of wildcards for simple pattern
+								matching is also possible. It supports the
+								following simple pattern styles: 'xxx*', '*xxx',
+								'*xxx*' and 'xxx*yyy'.
+							]]></xsd:documentation>
+						</xsd:annotation>
+					</xsd:attribute>
+					<xsd:attribute name="xsl-resource" type="xsd:string" use="optional">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								Allows you to specify a org.springframework.core.io.Resource,
+								which will be used to create the javax.xml.transform.Templates
+								instance.
+
+								Either this attribute or the 'xsl-templates'
+								attribute MUST be specified.
+							]]></xsd:documentation>
+						</xsd:annotation>
+					</xsd:attribute>
 					<xsd:attribute name="xsl-templates" type="xsd:string" use="optional">
 						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								Reference to a Templates instance.
+
+								Either this attribute or the 'xsl-resource'
+								attribute MUST be specified.
+							]]></xsd:documentation>
 							<xsd:appinfo>
 								<tool:annotation kind="ref">
 									<tool:expected-type type="javax.xml.transform.Templates"/>
@@ -123,6 +170,12 @@
 					</xsd:attribute>
 					<xsd:attribute name="source-factory" type="xsd:string" use="optional">
 						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								Reference to a 'SourceFactory' instance. Allows
+								for the custom conversion to a javax.xml.transform.Source
+								If not set, this property will internally default
+								to 'DomSourceFactory'.
+							]]></xsd:documentation>
 							<xsd:appinfo>
 								<tool:annotation kind="ref">
 									<tool:expected-type type="org.springframework.integration.xml.source.SourceFactory"/>
@@ -132,6 +185,11 @@
 					</xsd:attribute>
 					<xsd:attribute name="result-factory" type="xsd:string" use="optional">
 						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								Reference to a custom implementation of 'ResultFactory'.
+								If this attribute is provided, you must not specify
+								the 'result-type' attribute.
+							]]></xsd:documentation>
 							<xsd:appinfo>
 								<tool:annotation kind="ref">
 									<tool:expected-type type="org.springframework.integration.xml.result.ResultFactory"/>
@@ -140,6 +198,18 @@
 						</xsd:annotation>
 					</xsd:attribute>
 					<xsd:attribute name="result-type" use="optional">
+						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								This attribute can be used to control the type
+								of result created.
+
+								If this attribute is provided, you must not specify
+								the 'result-factory' attribute.
+
+								If neither this property nor the 'result-factory'
+								attribute are provided, 'DomResult' will be used.
+							]]></xsd:documentation>
+						</xsd:annotation>
 						<xsd:simpleType>
 							<xsd:restriction base="xsd:string">
 								<xsd:enumeration value="DOMResult"/>
@@ -149,6 +219,17 @@
 					</xsd:attribute>
 					<xsd:attribute name="result-transformer" type="xsd:string" use="optional">
 						<xsd:annotation>
+							<xsd:documentation><![CDATA[
+								If the XSLT transformation returns a 'Result' object,
+								than you have the option to specify a reference
+								to a 'ResultTransformer' instance. This allows
+								you to transform the 'Result' into another format.
+
+								By default 2 implementations are available:
+
+								- 'ResultToDocumentTransformer' and
+								- 'ResultToStringTransformer'
+							]]></xsd:documentation>
 							<xsd:appinfo>
 								<tool:annotation kind="ref">
 									<tool:expected-type type="org.springframework.integration.xml.transformer.ResultTransformer"/>