From 394efd2a2a14959e5d4ecfc8e3bd2a8828f6c21d Mon Sep 17 00:00:00 2001
From: Oleg Zhurakousky <ozhurakousky@vmware.com>
Date: Wed, 15 Sep 2010 22:43:41 -0400
Subject: [PATCH] INT-1438, added XPath transformer documentation

---
 .../integration/xml/XmlPayloadConverter.java  |   2 +-
 src/docbkx/xml.xml                            | 100 +++++++++++++++++-
 2 files changed, 100 insertions(+), 2 deletions(-)

diff --git a/spring-integration-xml/src/main/java/org/springframework/integration/xml/XmlPayloadConverter.java b/spring-integration-xml/src/main/java/org/springframework/integration/xml/XmlPayloadConverter.java
index d9c2cd74b1..0a92c04b0e 100644
--- a/spring-integration-xml/src/main/java/org/springframework/integration/xml/XmlPayloadConverter.java
+++ b/spring-integration-xml/src/main/java/org/springframework/integration/xml/XmlPayloadConverter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2010 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.
diff --git a/src/docbkx/xml.xml b/src/docbkx/xml.xml
index d260ae908e..cf75252e3d 100644
--- a/src/docbkx/xml.xml
+++ b/src/docbkx/xml.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
 <chapter id="xml">
-	<title>Dealing with XML Payloads</title>
+	<title>XML Support - Dealing with XML Payloads</title>
 
 	<section id="xml-intro">
 		<title>Introduction</title>
@@ -328,6 +328,104 @@
 </bean>]]></programlisting>
 	</section>
 	
+	<section id="xpath-transformer">
+		<title>Transforming xml messages using XPath</title>
+		<para>
+			When it comes to message transformation XPath is a great way to transform Messages that have XML 
+			payloads by defining XPath transformers via <emphasis>xpath-transformer</emphasis> element.
+		</para>
+		<para>
+		<emphasis>Simple XPath transformation</emphasis>
+		</para>
+		<para>
+		Let's look at the following transformer configuration:
+		<programlisting language="xml"><![CDATA[<xpath-transformer input-channel="inputChannel" output-channel="outputChannel" 
+			xpath-expression="/person/@name" />]]></programlisting>
+		
+		. . . and Message
+		<programlisting language="java"><![CDATA[Message<?> message = 
+	MessageBuilder.withPayload("<person name='John Doe' age='42' married='true'/>").build();]]></programlisting>
+		After sending this message to the 'inputChannel' the XPath transformer configured above will transform 
+		this XML Message to a simple Message with payload of 'John Doe' all based on 
+		the simple XPath Expression specified in the <emphasis>xpath-expression</emphasis> attribute.
+		</para>
+		<para>
+		XPath also has capability to perform simple conversion of extracted elements 
+		to a desired type. Valid return types are defined in <classname>XPathConstants</classname> and follows 
+		the conversion rules specified by the <classname>XPath</classname>.
+		</para>
+		<para>
+		The following constants are defined by the <classname>XPathConstants</classname>: <emphasis>BOOLEAN, DOM_OBJECT_MODEL, NODE, NODESET, NUMBER, STRING</emphasis>
+		</para>
+		<para>
+		You can configure the desired type by simply using <emphasis>evaluation-type</emphasis> 
+		attribute of the <emphasis>xpath-transformer</emphasis> element.
+		<programlisting language="xml"><![CDATA[<xpath-transformer input-channel="numberInput" xpath-expression="/person/@age" 
+		evaluation-type="NUMBER_RESULT" output-channel="output"/>
+
+<xpath-transformer input-channel="booleanInput" xpath-expression="/person/@married = 'true'" 
+		evaluation-type="BOOLEAN_RESULT" output-channel="output"/>
+]]></programlisting>
+		</para>
+		<para>
+		<emphasis>Node Mappers</emphasis>
+		</para>
+		<para>
+		If you need to provide custom mapping for the node extracted by the XPath expression simply provide a reference to the 
+		implementation of the <classname>org.springframework.xml.xpath.NodeMapper</classname> - an interface used by 
+		<classname>XPathOperations</classname> implementations for mapping Node objects on a per-node basis. To provide a 
+		reference to a <classname>NodeMapper</classname> simply use <emphasis>node-mapper</emphasis> attribute:
+		<programlisting language="xml"><![CDATA[<xpath-transformer input-channel="nodeMapperInput" xpath-expression="/person/@age" 
+		node-mapper="testNodeMapper" output-channel="output"/>
+]]></programlisting>
+. . . and Sample NodeMapper implementation:
+<programlisting language="java"><![CDATA[class TestNodeMapper implements NodeMapper {
+	public Object mapNode(Node node, int nodeNum) throws DOMException {
+		return node.getTextContent() + "-mapped";
+	}
+}]]></programlisting>
+		</para>
+		<para>
+		<emphasis>XML Payload Converter</emphasis>
+		</para>
+		<para>
+		You can also use implementation of the <classname>org.springframework.integration.xml.XmlPayloadConverter</classname> to 
+		provide more granular transformation:	
+		<programlisting language="xml"><![CDATA[<xpath-transformer input-channel="customConverterInput" xpath-expression="/test/@type" 
+		converter="testXmlPayloadConverter" output-channel="output"/>
+]]></programlisting>
+. . . and Sample XmlPayloadConverter implementation:
+<programlisting language="java"><![CDATA[class TestXmlPayloadConverter implements XmlPayloadConverter {
+	public Source convertToSource(Object object) {
+		throw new UnsupportedOperationException();
+	}
+	//
+	public Node convertToNode(Object object) {
+		try {
+			return DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(
+					new InputSource(new StringReader("<test type='custom'/>")));
+		}
+		catch (Exception e) {
+			throw new IllegalStateException(e);
+		}
+	}
+	//
+	public Document convertToDocument(Object object) {
+		throw new UnsupportedOperationException();
+	}
+}]]></programlisting>
+		</para>
+		<para>
+		<emphasis>Combination of SpEL and XPath expressions</emphasis>
+		</para>
+		<para>
+		You can also combine Spring Expression Language (SpEL) expressions with XPath expression and configure 
+		them using <emphasis>expression</emphasis> attribute:
+		<programlisting language="xml"><![CDATA[xpath-expression id="testExpression" expression="/person/@age * 2"/>]]></programlisting>
+		In the above case the overall result of the expression will be the result of the XPathe expression multiplied by 2.
+		</para>	
+	</section>
+	
 	
 	<section id="xpath-namespace-support">
 		<title>XPath components namespace support</title>