work in progress documentation for xml module

spring-integration-reference/src/xml.xml

@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="xml">
+	<title>Dealing with XML payloads</title>
+
+	<section id="xml-intro">
+		<title>Introduction</title>
+		<para>
+			Spring Integration XML extends the Spring Integration Core with 
+			implementations of splitter, transformer, selector and routers designed 
+			to make working with XML in Spring Integration simple.  The provided messaging 
+			components are designed to work with XML represented in a range of formats including 
+			instances of 
+			<classname>java.lang.String</classname>, <interfacename>org.w3c.dom.Document</interfacename>  
+			and <interfacename>javax.xml.transform.Source</interfacename>
+		
+    	</para>
+	</section>
+	<section id="xml-transformation">
+		<title>Transforming XML payloads</title>
+		<para>
+			This section will explain the workings of
+			<classname>XmlPayloadUnmarshallingTransformer</classname>,
+			<classname>XmlPayloadMarshallingTransformer</classname>
+			<classname>XsltPayloadTransformer</classname>
+			and how to configure them as
+			<emphasis>beans</emphasis>.  
+			Also how to customise which implementation of 
+			<interfacename>javax.xml.transfrom.Source</interfacename> 
+			and <interfacename>javax.xml.Result</interfacename>
+			Finally the namespace support will be discussed.
+		</para>
+		<para>
+			<classname>XmlPayloadUnmarshallingTransformer</classname> allows an XML Source 
+			to be unmarshalled using an implementations of Spring OXM <interfacename>Unmarshaller</interfacename>.  
+			Spring OXM provides several implementations supporting Marshalling and Unmarshalling using JAXB, 
+			Castor and JiBX amongest others.  Since the <interfacename>Unmarshaller</interfacename> requires an instance of 
+			<interfacename>Source</interfacename> where the message payload is not currently an instance of
+			<interfacename>Source</interfacename> conversion will be attempted.  Currently <classname>String</classname>
+			and <interfacename>org.w3c.dom.Document</interfacename> payloads are supported.  Custom conversion can 
+			also be carried out by providing an implementation of <interfacename>SourceFactory</interfacename>.
+			<programlisting language="xml"><![CDATA[<bean id="unmarshallingTransfomer" class="org.springframework.integration.xml.transformer.XmlPayloadUnmarshallingTransformer">
+    <constructor-arg>
+        <bean class="org.springframework.oxm.jaxb.Jaxb1Marshaller">
+		    <property name="contextPath" value="org.example" />
+        </bean>
+    </constructor-arg>
+</bean>]]></programlisting>
+			A transformer configured as above can be used in conjunction with an instance of 
+			<classname>MessageTransformingConsumer</classname> to consume messages from one 
+			channel and send transformed messages to another channel.  However the namespace 
+			support discussed later conceals the need for any additional beans. 
+		</para>	
+		<para>
+			The <classname>XmlPayloadMarshallingTransformer</classname> allows an Object graph to be 
+			converted into XML using a Spring OXM <interfacename>Marshaller</interfacename>.
+			By default the <classname>XmlPayloadMarshallingTransformer</classname> will return
+			a <classname>DomResult</classname>.  However this can be controlled by configuring an 
+			alternative <interfacename>ResultFactory</interfacename> such as 
+			<classname>StringResultFactory</classname>.  In many cases it will be more convenient to transform
+			the payload into an alternative XML format.  To achieve this configure a 
+			<interfacename>ResultTransformer</interfacename> two implementations are provided one which 
+			converts to <classname>String</classname> and another which converts to <interfacename>Document</interfacename>  
+			<programlisting language="xml"><![CDATA[<bean id="marshallingTransfomer" class="org.springframework.integration.xml.transformer.XmlPayloadMarshallingTransformer">
+    <constructor-arg>
+        <bean class="org.springframework.oxm.jaxb.Jaxb1Marshaller">
+            <property name="contextPath" value="org.example" />
+        </bean>
+    </constructor-arg>
+    <constructor-arg>
+        <bean class="org.springframework.integration.xml.transformer.ResultToDocumentTransformer" />
+    </constructor-arg>
+</bean>]]></programlisting>			
+		</para>
+		<para>
+			<classname>XsltPayloadTransformer</classname> transforms XML payloads using XSL.
+			The transformer requires an instance of either <interfacename>Resource</interfacename> or 
+			<interfacename>Templates</interfacename>.  Passing in a <interfacename>Templates</interfacename> 
+			allows for greater configuration of the <interfacename>Transformer</interfacename> used to create
+			the <interfacename>Templates</interfacename> instance.  As in the case of 
+			<classname>XmlPayloadMarshallingTransformer</classname> by default <classname>XsltPayloadTransformer</classname>
+			will create a message with a <interfacename>Result</interfacename> payload.  This can be customised by 
+			providing a <interfacename>ResultFactory</interfacename> and or a <interfacename>ResultTransformer</interfacename>.
+			<programlisting language="xml">
+			<![CDATA[<bean id="xsltPayloadTransformer" class="org.springframework.integration.xml.transformer.XsltPayloadTransformer">
+    <constructor-arg value="classpath:org/example/xsl/transform.xsl" />
+    <constructor-arg>
+        <bean class="org.springframework.integration.xml.transformer.ResultToDocumentTransformer" />
+    </constructor-arg>
+</bean>]]></programlisting>			
+		</para>
+		<para>
+			Namespace support for all these transformers is provided in the Sprint Integration XML namespace 
+			a template for which is below.  The namespace support creates an instance of either <classname>SubscribingConsumerEndpoint</classname> 
+			or <classname>PollingConsumerEndpoint</classname> according to the type of the provided input channel.  The namespace support is designed 
+			to reduce the amount of xml configuration by allowing the creation of an endpoint and transformer using one element.
+						<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xmlns:integration="http://www.springframework.org/schema/integration"
+	xmlns:si-xml="http://www.springframework.org/schema/integration/xml"
+	xsi:schemaLocation="http://www.springframework.org/schema/beans
+			http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+			http://www.springframework.org/schema/integration
+			http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
+			http://www.springframework.org/schema/integration/xml
+			http://www.springframework.org/schema/integration/xml/spring-integration-xml-1.0.xsd">
+</beans>]]></programlisting>
+		So for example an <classname>XmlPayloadMarshallingTransformer</classname> can be configured as below.
+		<programlisting language="xml"><![CDATA[<si-xml:unmarshalling-transformer id="defaultUnmarshaller"
+			input-channel="input"
+			output-channel="output"
+			unmarshaller="unmarshaller"/>]]></programlisting>
+		<programlisting language="xml"><![CDATA[<si-xml:marshalling-transformer
+		input-channel="marshallingTransformerStringResultFactory"
+		output-channel="output"
+		marshaller="marshaller"
+		result-type="StringResult" />]]></programlisting>
+				
+		</para>
+	</section>
+
+	<section id="xpath-routing">
+		<title>Routing XML payloads using XPath</title>
+		<para>
+		</para>
+
+	</section>
+	
+	<section id="xpath-splitting">
+		<title>Splitting XML payloads using XPath</title>
+		<para>
+		</para>
+
+	</section>
+	
+	<section id="xpath-selector">
+		<title>Splitting XML payloads using XPath</title>
+		<para>
+		</para>
+	</section>
+	
+	
+	
+	
+</chapter>