From d893ba45ea0776c06bfcb58aa283a156ea7d8fa6 Mon Sep 17 00:00:00 2001 From: Jonas Partner Date: Sun, 19 Oct 2008 12:06:02 +0000 Subject: [PATCH] documentation for SI xml module --- spring-integration-reference/src/xml.xml | 234 ++++++++++++++++------- 1 file changed, 163 insertions(+), 71 deletions(-) diff --git a/spring-integration-reference/src/xml.xml b/spring-integration-reference/src/xml.xml index eb4fc1123b..db4a8b541d 100644 --- a/spring-integration-reference/src/xml.xml +++ b/spring-integration-reference/src/xml.xml @@ -1,33 +1,32 @@ - Dealing with XML payloads + Dealing with xml payloads
Introduction - Spring Integration XML extends the Spring Integration Core with - implementations of splitter, transformer, selector and routers designed + Spring Integration xml extends the Spring Integration Core with + implementations of splitter, transformer, selector and router designed to make working with xml messages in Spring Integration simple. The provided messaging components are designed to work with xml represented in a range of formats including instances of java.lang.String, org.w3c.dom.Document and javax.xml.transform.Source. It should be noted however that - where a Document or Node is required - for example in order to evaluate an XPath expression the String payload will - be converted into the required type and then converted back again which may incur significant - computational cost. Components that require an instance of - DocumentBuilder will create a namespace aware instance if one is not - provided. Where greater control of the document being created is required an appropriately configured - instance of DocumentBuilder should be provided. + where a dom representation is required, for example in order to evaluate an XPath expression, + the String payload will be converted into the required type and then + converted back again to String. Components that require an instance of + DocumentBuilder will create a namespace aware instance if one is + not provided. Where greater control of the document being created is required an appropriately + configured instance of DocumentBuilder should be provided.
Transforming xml payloads - + This section will explain the workings of XmlPayloadUnmarshallingTransformer, - XmlPayloadMarshallingTransformer + XmlPayloadMarshallingTransformer, XsltPayloadTransformer and how to configure them as beans. All of the provided xml transformers extend @@ -35,22 +34,21 @@ Transformer. When configuring xml transformers as beans in Spring Integration you would normally configure the transformer in conjunction with either a MessageTransformingChannelInterceptor or a - MessageTransformingConsumer in order to connect the transformer instance to - a channel. - Finally the namespace support will be discussed which allows simple configuration of the transformers as consumers. + MessageTransformingConsumer. This allows the transformer to be used as either an interceptor, + which transforms the message as it is sent or received to the channel, or as an endpoint. Finally the + namespace support will be discussed which allows for the simple configuration of the transformers as + MessageEndpoint instances. - - - - XmlPayloadUnmarshallingTransformer allows an XML Source - to be unmarshalled using an implementations of Spring OXM Unmarshaller. - Spring OXM provides several implementations supporting Marshalling and Unmarshalling using JAXB, - Castor and JiBX amongest others. Since the Unmarshaller requires an instance of + XmlPayloadUnmarshallingTransformer allows an xml Source + to be unmarshalled using implementations of Spring OXM Unmarshaller. + Spring OXM provides several implementations supporting marshalling and unmarshalling using JAXB, + Castor and JiBX amongst others. Since the unmarshaller requires an instance of Source where the message payload is not currently an instance of - Source conversion will be attempted. Currently String - and org.w3c.dom.Document payloads are supported. Custom conversion can - also be carried out by providing an implementation of SourceFactory. + Source, conversion will be attempted. Currently String + and org.w3c.dom.Document payloads are supported. Custom conversion to a + Source is also supported by injecting an implementation of + SourceFactory. @@ -58,21 +56,16 @@ ]]> - A transformer configured as above can be used in conjunction with an instance of - MessageTransformingConsumer 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. - The XmlPayloadMarshallingTransformer allows an Object graph to be - converted into xml using a Spring OXM Marshaller. - By default the XmlPayloadMarshallingTransformer will return - a DomResult. However this can be controlled by configuring an - alternative ResultFactory such as - StringResultFactory. In many cases it will be more convenient to transform + The XmlPayloadMarshallingTransformer allows an object graph to be converted + into xml using a Spring OXM Marshaller. By default the + XmlPayloadMarshallingTransformer will return a DomResult. + However the type of result can be controlled by configuring an alternative ResultFactory + such as StringResultFactory. In many cases it will be more convenient to transform the payload into an alternative xml format. To achieve this configure a - ResultTransformer two implementations are provided one which - converts to String and another which converts to Document + ResultTransformer. Two implementations are provided, one which converts to + String and another which converts to Document. @@ -85,14 +78,14 @@ ]]> - XsltPayloadTransformer transforms xml payloads using XSL. - The transformer requires an instance of either Resource or - Templates. Passing in a Templates - allows for greater configuration of the Transformer used to create - the Templates instance. As in the case of - XmlPayloadMarshallingTransformer by default XsltPayloadTransformer - will create a message with a Result payload. This can be customised by - providing a ResultFactory and or a ResultTransformer. + XsltPayloadTransformer transforms xml payloads using xsl. + The transformer requires an instance of either Resource or + Templates. Passing in a Templates instance + allows for greater configuration of the TransformerFactory used to create + the template instance. As in the case of XmlPayloadMarshallingTransformer + by default XsltPayloadTransformer will create a message with a + Result payload. This can be customised by providing a + ResultFactory and/or a ResultTransformer. @@ -100,14 +93,18 @@ ]]> +
+
+ + Namespace support for xml transformers - Namespace support for all these transformers is provided in the Sprint Integration xml namespace - a template for which can be seen below. The namespace support creates an instance of either + Namespace support for all xml transformers is provided in the Spring Integration xml namespace, + a template for which can be seen below. The namespace support for transformers creates an instance of either SubscribingConsumerEndpoint or PollingConsumerEndpoint 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. - + ]]> - So for example an XmlPayloadMarshallingTransformer can be configured as below. + The namespace support for XmlPayloadUnmarshallingTransformer is shown below. + Since the namespace is now creating an instance of MessageEndpoint rather + than a transformer a poller can also be nested within the element to control the polling of the input channel. ]]> + unmarshaller="unmarshaller"/> + + + + + + + ]]> + - - The namespace support for the marshalling transformer allows creation of an endpoint + + The namespace support for the marshalling transformer requires an input channel, output channel and a + reference to a marshaller. The optional result-type attribute can be used to control the type of result created, + valid values are StringResult or DomResult (the default). Where the provided result types are not sufficient a + reference to a custom implementation of ResultFactory can be provided as an alternative + to setting the result-type attribute using the result-factory attrbitue. An optional result-transformer can also be + specified in order to convert the created Result after marshalling. ]]> - - + + Namespace support for the XsltPayloadTransformer allows either a resource to be passed in in order to create the + Templates instance or alternatively a precreated Templates + instance can be passed in as a reference. In common with the marshalling transformer the type of the result output can + be controlled by specifying either the result-factory or result-type attribute. A result-transfomer attribute can also + be used to reference an implementation of ResultTransfomer where conversion of the result + is required before sending. ]]> + xsl-resource="org/springframework/integration/xml/config/test.xsl"/> +]]>
Splitting xml messages - XPathMessageSplitter support messages with either + XPathMessageSplitter supports messages with either String or Document payloads. The splitter uses the provided XPath expression to split the payload into a number of nodes. By default this will result in each Node instance becoming the payload of a new message. Where it is preferred that each message be a Document - the createDocuments flag can be set. Where a String payload is passed + the createDocuments flag can be set. Where a String payload is passed in the payload will be converted then split before being converted back to a number of String messages. The XPath splitter implements MessageConsumer and should therefore be configured in conjunction with an appropriate endpoint. @@ -180,8 +205,8 @@
Routing xml messages using XPath - Two Router implementations based on XPath are provided XPathSingleChannelRouter and - XPathMultiChannelRouter. The implementations differ in respect of how many channels + Two Router implementations based on XPath are provided XPathSingleChannelRouter and + XPathMultiChannelRouter. The implementations differ in respect to how many channels any given message may be routed to, exactly one in the case of the single channel version or zero or more in the case of the multichannel router. Both evaluate an XPath expression against the xml payload of the message, supported payload types by default @@ -190,10 +215,10 @@ of XmlPayloadConverter can be provided. The router implementations use ChannelNameResolver to convert the result(s) of the XPath expression to a channel name. By default a - BeanFactoryChannelName meaning that the string returned by the XPath + BeanFactoryChannelName strategy will be used, this means that the string returned by the XPath evaluation should correspond directly to the name of a channel. Where this is not the case an alternative implementation of ChannelNameResolver can - be used, where there is a simple mapping from Xpath result to channel name + be used. Where there is a simple mapping from Xpath result to channel name the provided MapBasedChannelName can be used. @@ -230,17 +255,14 @@
- Selecting xml messages use XPath + Selecting xml messages using XPath - Two MessageSelector implementations are provided - BooleanTestXPathMessageSelector and - StringValueTestXPathMessageSelector. - BooleanTestXPathMessageSelector requires an XPathExpression which - evaluates to a boolean, for example boolean(/one/two) which will only - select messages which have an element named two which is a child of a root element named one. - StringValueTestXPathMessageSelector evaluates any XPath expression as - a Stringand compares the result with the provided - String value. + Two MessageSelector implementations are provided, + BooleanTestXPathMessageSelector and StringValueTestXPathMessageSelector. + BooleanTestXPathMessageSelector requires an XPathExpression which evaluates to a boolean, + for example boolean(/one/two) which will only select messages which have an element named + two which is a child of a root element named one. StringValueTestXPathMessageSelector + evaluates any XPath expression as a String and compares the result with the provided value. @@ -265,6 +287,76 @@
+
+ XPath components namespace support + All XPath based components have namespace support allowing them to be configured as instances of + MessageEndpoint with the exception of the XPath selectors which are not designed to act as + endpoints. Each component allows the XPath to either be referenced at the top level or configured via a nested + xpath-expression element. So the following configurations of an xpath-selector are all valid and represent the general + form of XPath namespace support. All forms of XPath expression result in the creation of an + XPathExpression using the Spring XPathExpressionFactory + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + XPath splitter namespace support allows the creation of a MessageEndpoint with an input channel and output channel. + + + + + + + + + + + +]]> + + + XPath router namespace support allows for the creation of a MessageEndpoint with an input channel but no output channel + since the output channel is determined dynamically. The multi-channel attribute causes the creation of a multi channel router capable of + routing a single message to many channels when true and a single channel router when false. + + + + + + + + + + + +]]> + + + +
\ No newline at end of file