diff --git a/spring-integration-xml/src/main/java/org/springframework/integration/xml/config/XsltPayloadTransformerParser.java b/spring-integration-xml/src/main/java/org/springframework/integration/xml/config/XsltPayloadTransformerParser.java index 59c24cfad5..34ec33df53 100644 --- a/spring-integration-xml/src/main/java/org/springframework/integration/xml/config/XsltPayloadTransformerParser.java +++ b/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"); } diff --git a/spring-integration-xml/src/main/java/org/springframework/integration/xml/transformer/ResultTransformer.java b/spring-integration-xml/src/main/java/org/springframework/integration/xml/transformer/ResultTransformer.java index 62c73b0a6b..4c4be4fafe 100644 --- a/spring-integration-xml/src/main/java/org/springframework/integration/xml/transformer/ResultTransformer.java +++ b/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 { diff --git a/spring-integration-xml/src/main/resources/org/springframework/integration/xml/config/spring-integration-xml-2.2.xsd b/spring-integration-xml/src/main/resources/org/springframework/integration/xml/config/spring-integration-xml-2.2.xsd index 8de0e0964c..58c6ebff3a 100644 --- a/spring-integration-xml/src/main/resources/org/springframework/integration/xml/config/spring-integration-xml-2.2.xsd +++ b/spring-integration-xml/src/main/resources/org/springframework/integration/xml/config/spring-integration-xml-2.2.xsd @@ -108,12 +108,59 @@ - + + + + + - - + + + + + + + + + + + @@ -123,6 +170,12 @@ + @@ -132,6 +185,11 @@ + @@ -140,6 +198,18 @@ + + + @@ -149,6 +219,17 @@ + diff --git a/src/reference/docbook/xml.xml b/src/reference/docbook/xml.xml index e5a5f9fe73..dab2b9df25 100644 --- a/src/reference/docbook/xml.xml +++ b/src/reference/docbook/xml.xml @@ -228,81 +228,101 @@ -
- Transforming XML Payloads -
- Configuring Transformers as Beans - - This section will explain the workings of the following transformers - and how to configure them as beans: - - - - - UnmarshallingTransformer - - - MarshallingTransformer - - - XsltPayloadTransformer - - - - - All of the provided XML transformers extend - AbstractTransformer or AbstractPayloadTransformer - and therefore implement Transformer. When configuring XML - transformers as beans in Spring Integration you would normally configure the transformer - in conjunction with either a MessageTransformingChannelInterceptor or a - MessageTransformingHandler. 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 - elements in XML. - - - UnmarshallingTransformer 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 to a - Source is also supported by injecting an implementation of - SourceFactory. - - - +
+ Transforming XML Payloads +
+ Configuring Transformers as Beans + + This section will explain the workings of the following transformers + and how to configure them as beans: + + + + UnmarshallingTransformer + + + MarshallingTransformer + + + XsltPayloadTransformer + + + + All of the provided XML transformers extend + AbstractTransformer + or AbstractPayloadTransformer + and therefore implement + Transformer. + When configuring XML transformers as beans in Spring Integration, + you would normally configure the Transformer + in conjunction with either a + MessageTransformingChannelInterceptor + or a MessageTransformingHandler. + 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 elements in XML. + +
+ UnmarshallingTransformer + + An UnmarshallingTransformer + allows an XML Source to be + unmarshalled using implementations of the + Spring OXM + Unmarshaller. Spring's Object/XML Mapping + support provides several implementations supporting marshalling + and unmarshalling using + JAXB, + Castor and + JiBX amongst others. + The unmarshaller requires an instance of Source. + If the message payload is not an instance of Source, + conversion will be attempted. Currently String, + File and org.w3c.dom.Document + payloads are supported. Custom conversion to a Source + is also supported by injecting an implementation of a + SourceFactory. + + + If a SourceFactory is not set + explicitly, the property on the UnmarshallingTransformer + will by default be set to a + DomSourceFactory. + + - + ]]> - - - The MarshallingTransformer allows an object graph to be converted - into XML using a Spring OXM Marshaller. By default the - MarshallingTransformer 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. - - - - - - - - - - - +
+
+ MarshallingTransformer + + The MarshallingTransformer + allows an object graph to be converted into XML using a Spring OXM + Marshaller. By default the + MarshallingTransformer 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. + + + + + + + + + + ]]> @@ -314,27 +334,98 @@ payload is the appropriate source Object for marshalling when delegating to any of the various out-of-the-box Marshaller implementations. - - 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. - - - +
+
+ XsltPayloadTransformer + + XsltPayloadTransformer + transforms XML payloads using Extensible Stylesheet Language Transformations (XSLT). + The transformer's constructor requires an instance of either + Resource + or Templates + to be passed in. Passing in a Templates + instance allows for greater configuration of the TransformerFactory + used to create the template instance. + + + As with the UnmarshallingTransformer, + the XsltPayloadTransformer will do the actual + XSLT transformation using instances of Source. + Therefore, if the message payload is not an instance of Source, + conversion will be attempted. String and + Document payloads are supported directly. + + + Custom conversion to a Source is also + supported by injecting an implementation of a + SourceFactory. + + + If a SourceFactory is not set + explicitly, the property on the XsltPayloadTransformer + will by default be set to a + DomSourceFactory. + + + By default, the XsltPayloadTransformer will create a message + with a + Result + payload, similar to the XmlPayloadMarshallingTransformer. + This can be customised by providing a + ResultFactory + and/or a ResultTransformer. + + - + ]]> +
+
+ ResultTransformers + + Both the MarshallingTransformer and the + XsltPayloadTransformer allow you to specify a + ResultTransformer. + Thus, if the Marshalling or XSLT transformation returns a Result, + than you have the option to also use a ResultTransformer + to transform the Result into another + format. Spring Integration provides 2 concrete + ResultTransformer implementations: + + + ResultToDocumentTransformer + ResultToStringTransformer + -
+ Using ResultTransformers with the MarshallingTransformer + + By default, the MarshallingTransformer will always + return a Result. + By specifying a ResultTransformer, you can customize the + type of payload returned. + + Using ResultTransformers with the XsltPayloadTransformer + + The behavior is slighly more complex for the XsltPayloadTransformer. + By default, if the input payload is an instance of String + or Document + the resultTransformer property is ignored. + + + However, if the input payload is a + Source + or any other type, then the resultTransformer property is + applied. Additionally, you can set the property alwaysUseResultFactory + to true, which will also cause the specified resultTransformer to + being used. + + + For more information and examples, please see + +
+
Namespace Support for XML Transformers @@ -345,33 +436,32 @@ to reduce the amount of XML configuration by allowing the creation of an endpoint and transformer using one element. - - The namespace support for UnmarshallingTransformer is shown below. - Since the namespace is now creating an endpoint instance rather than a transformer, - a poller can also be nested within the element to control the polling of the input channel. - - UnmarshallingTransformer + + The namespace support for the UnmarshallingTransformer + is shown below. Since the namespace is now creating an endpoint instance + rather than a transformer, a poller can also be nested within the + element to control the polling of the input channel. + + ]]> - - 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 attribute. An optional result-transformer can also be - specified in order to convert the created Result after marshalling. - - - MarshallingTransformer + + 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). + + -]]> - - - 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. - - ]]> + + 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 attribute. The attributes + result-type and result-factory + are mutually exclusive. + + + Internally, the result types StringResult and DomResult + are represented by the ResultFactorys + StringResultFactory + and DomResultFactory + respectively. + + XsltPayloadTransformer + + Namespace support for the XsltPayloadTransformer + allows you to either pass in a Resource, + in order to create the + Templates + instance, + or alternatively, you can pass in a precreated Templates + instance 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. + + + If you specify the result-factory or the result-type + attribute, then the alwaysUseResultFactory property on + the underlying + XsltPayloadTransformer + will be set to true by the + XsltPayloadTransformerParser. + + + ]]> - - Very often to assist with transformation you may need to have access to Message data (e.g., Message Headers). For example; you may need to get access to certain Message Headers - and pass them on as parameters to a transformer (e.g., transformer.setParameter(..)).  - Spring Integration provides two convenient ways to accomplish this. Just look at the following XML snippet. - + Often you may need to have access to Message data, such as the + Message Headers, in order to assist with transformation. For example, + you may need to get access to certain Message Headers and pass them + on as parameters to a transformer (e.g., transformer.setParameter(..)). + Spring Integration provides two convenient ways to accomplish this, as + illustrated in following example: + + + ]]> - If message header names match 1:1 to parameter names, you can simply use xslt-param-headers attribute. There you can also use wildcards for - simple pattern matching which supports the following simple pattern styles: "xxx*", "*xxx", "*xxx*" and "xxx*yyy". - - - You can also configure individual xslt parameters via <xslt-param/> sub element. There you can use expression or value attribute. - The expression attribute should be any valid SpEL expression with 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 scalar vallue. YOu can also use property placeholders (e.g., ${some.value}) - So as you can see, with the expression and value attribute xslt parameters could now be mapped to any accessible part of the Message as well as any literal value. - -
-
+ + + If message header names match 1:1 to parameter names, you can simply use + xslt-param-headers attribute. There you can also use wildcards + for simple pattern matching, which supports the following simple pattern + styles: "xxx*", "*xxx", "*xxx*" and "xxx*yyy". + + + You can also configure individual Xslt parameters via the <xslt-param/> + sub element. There you can use either the expression or + value attribute. + The expression attribute should be any valid SpEL expression + with 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 scalar values. You can + also use property placeholders (e.g., ${some.value}). So as you can + see, with the expression and value attribute, + Xslt parameters could now be mapped to any accessible part of the Message + as well as any literal value. + +
+
+ Namespace Configuration and ResultTransformers + + The usage of ResultTransformers was + previously introduced in . + The following example illustrates several special use-cases using XML + namespace configuration. First, we define the + ResultTransformer: + + ]]> + + This ResultTransformer will accept either + a StringResult or a DOMResult + as input and converts the input into a Document. + + + Now, let's declare the transformer: + + ]]> + + If the incoming message's payload is of type Source, + then as first step the Result is determined + using the ResultFactory. As we did not + specify a ResultFactory, the default + DomResultFactory is used, meaning that the + transformation will yield a DomResult. + + + However, as we specified a ResultTransformer, it + will be used and the resulting Message payload will be of type + Document. + + + If the incoming message's payload is of type String, + the payload after the Xslt transformation will be a String. Similarly, + if the incoming message's payload is of type Document, + the payload after the Xslt transformation will be a + Document. The specified + ResultTransformer will be ignored with + String or Document + payloads. + + + If the message payload is neither a Source, + String or Document, + as a fallback option, it is attempted to create a + Source using the default + SourceFactory. + As we did not specify a SourceFactory + explicitly using the source-factory attribute, + the default DomSourceFactory + is used. If successful, the XSLT transformation is executed as if + the payload was of type Source, which + we described in the previous paragraphs. + + + The DomSourceFactory supports the creation of + a DOMSource from a either + Document, File + or String payloads. + + + The next transformer declaration adds a result-type + attribute using StringResult as its value. First, the + result-type is internally represented by the + StringResultFactory. Thus, you could have also + added a reference to a StringResultFactory, using + the result-factory attribute, which would haven + been the same. + + ]]> + + Because we are using a ResultFactory, the + alwaysUseResultFactory property of the + XsltPayloadTransformer class will be implicitly + set to true. Consequently, the referenced + ResultToDocumentTransformer will be used. + + + Therefore, if you transform a payload of type + String, the resulting payload will be of type + Document. + +
+
Transforming XML Messages Using XPath