Spring Integration’s XML support extends the core of Spring Integration with the following components:

These components are 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 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. In cases where you require greater control over document creation, you can provide an appropriately configured instance of DocumentBuilder.

All components within the Spring Integration XML module provide namespace support. In order to enable namespace support, you need to import the respective schema for the Spring Integration XML Module. A typical setup is shown below:

<?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:int="http://www.springframework.org/schema/integration"
  xmlns:int-xml="http://www.springframework.org/schema/integration/xml"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/integration
    http://www.springframework.org/schema/integration/spring-integration.xsd
    http://www.springframework.org/schema/integration/xml
    http://www.springframework.org/schema/integration/xml/spring-integration-xml.xsd">
</beans>

When it comes to message transformation XPath is a great way to transform Messages that have XML payloads by defining XPath transformers via <xpath-transformer/> element.

Simple XPath transformation

Let’s look at the following transformer configuration:

<int-xml:xpath-transformer input-channel="inputChannel" output-channel="outputChannel"
      xpath-expression="/person/@name" />

...and Message

Message<?> message =
  MessageBuilder.withPayload("<person name='John Doe' age='42' married='true'/>").build();

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 xpath-expression attribute.

XPath also has the capability to perform simple conversion of extracted elements to a desired type. Valid return types are defined in javax.xml.xpath.XPathConstants and follows the conversion rules specified by the javax.xml.xpath.XPath interface.

The following constants are defined by the XPathConstants class: BOOLEAN, DOM_OBJECT_MODEL, NODE, NODESET, NUMBER, STRING

You can configure the desired type by simply using the evaluation-type attribute of the <xpath-transformer/> element.

<int-xml:xpath-transformer input-channel="numberInput" xpath-expression="/person/@age"
                           evaluation-type="NUMBER_RESULT" output-channel="output"/>

<int-xml:xpath-transformer input-channel="booleanInput"
                           xpath-expression="/person/@married = 'true'"
                           evaluation-type="BOOLEAN_RESULT" output-channel="output"/>

Node Mappers

If you need to provide custom mapping for the node extracted by the XPath expression simply provide a reference to the implementation of the org.springframework.xml.xpath.NodeMapper - an interface used by XPathOperations implementations for mapping Node objects on a per-node basis. To provide a reference to a NodeMapper simply use node-mapper attribute:

<int-xml:xpath-transformer input-channel="nodeMapperInput" xpath-expression="/person/@age"
                           node-mapper="testNodeMapper" output-channel="output"/>

...and Sample NodeMapper implementation:

class TestNodeMapper implements NodeMapper {
  public Object mapNode(Node node, int nodeNum) throws DOMException {
    return node.getTextContent() + "-mapped";
  }
}

XML Payload Converter

You can also use an implementation of the org.springframework.integration.xml.XmlPayloadConverter to provide more granular transformation:

<int-xml:xpath-transformer input-channel="customConverterInput"
                           output-channel="output" xpath-expression="/test/@type"
                           converter="testXmlPayloadConverter" />

...and Sample XmlPayloadConverter implementation:

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();
  }
}

The DefaultXmlPayloadConverter is used if this reference is not provided, and it should be sufficient in most cases since it can convert from Node, Document, Source, File, String, InputStream and byte[] typed payloads. If you need to extend beyond the capabilities of that default implementation, then an upstream Transformer is probably a better option than providing a reference to a custom implementation of this strategy here.

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 in the payload will be converted then split before being converted back to a number of String messages. The XPath splitter implements MessageHandler and should therefore be configured in conjunction with an appropriate endpoint (see the namespace support below for a simpler configuration alternative).

<bean id="splittingEndpoint"
      class="org.springframework.integration.endpoint.EventDrivenConsumer">
    <constructor-arg ref="orderChannel" />
    <constructor-arg>
        <bean class="org.springframework.integration.xml.splitter.XPathMessageSplitter">
            <constructor-arg value="/order/items" />
            <property name="documentBuilder" ref="customisedDocumentBuilder" />
            <property name="outputChannel" ref="orderItemsChannel" />
        </bean>
    </constructor-arg>
</bean>

XPath splitter namespace support allows the creation of a Message Endpoint with an input channel and output channel.

<!-- Split the order into items creating a new message for each item node -->
<int-xml:xpath-splitter id="orderItemSplitter"
                       input-channel="orderChannel"
                       output-channel="orderItemsChannel">
    <int-xml:xpath-expression expression="/order/items"/>
</int-xml:xpath-splitter>

<!-- Split the order into items creating a new document for each item-->
<int-xml:xpath-splitter id="orderItemDocumentSplitter"
                       input-channel="orderChannel"
                       output-channel="orderItemsChannel"
                       create-documents="true">
    <int-xml:xpath-expression expression="/order/items"/>
    <int:poller fixed-rate="2000"/>
</int-xml:xpath-splitter>

Starting with version 4.2, the XPathMessageSplitter exposes outputProperties (such as OutputKeys.OMIT_XML_DECLARATION) property for the javax.xml.transform.Transformer instances when a request payload isn’t of org.w3c.dom.Node type:

<util:properties id="outputProperties">
	<beans:prop key="#{T (javax.xml.transform.OutputKeys).OMIT_XML_DECLARATION}">yes</beans:prop>
</util:properties>

<xpath-splitter input-channel="input"
             output-properties="outputProperties">
    <xpath-expression expression="/orders/order"/>
</xpath-splitter>

Starting with version 4.2, the XPathMessageSplitter exposes an iterator option as a boolean flag (defaults to true). This allows the "streaming" of split nodes in the downstream flow. With the iterator mode, each node is transformed while iterating. When false, all entries are transformed first, before the split nodes start being sent to the output channel (transform, send, transform, send Vs. transform, transform, send, send). See Section 6.3, “Splitter” for more information.

Similar to SpEL-based routers, Spring Integration provides support for routing messages based on XPath expressions, allowing you to create a Message Endpoint with an input channel but no output channel. Instead, one or more output channels are determined dynamically.

<int-xml:xpath-router id="orderTypeRouter" input-channel="orderChannel">
    <int-xml:xpath-expression expression="/order/type"/>
</int-xml:xpath-router>

Internally XPath expressions will be evaluated as NODESET type and converted to a List<String> representing channel names. Typically such a list will contain a single channel name. However, based on the results of an XPath Expression, the XPath router can also take on the characteristics of a Recipient List Router if the XPath Expression returns more then one value. In that case, the List<String> will contain more then one channel name and consequently Messages will be sent to all channels in the list.

Thus, assuming that the XML file passed to the router configured below contains many responder sub-elements representing channel names, the message will be sent to all of those channels.

<!-- route the order to all responders-->
<int-xml:xpath-router id="responderRouter" input-channel="orderChannel">
    <int-xml:xpath-expression expression="/request/responders"/>
</int-xml:xpath-router>

If the returned values do not represent the channel names directly, additional mapping parameters can be specified, in order to map those returned values to actual channel names. For example if the /request/responders expression results in two values responderA and responderB but you don’t want to couple the responder names to channel names, you may provide additional mapping configuration such as the following:

<!-- route the order to all responders-->
<int-xml:xpath-router id="responderRouter" input-channel="orderChannel">
    <int-xml:xpath-expression expression="/request/responders"/>
    <int-xml:mapping value="responderA" channel="channelA"/>
    <int-xml:mapping value="responderB" channel="channelB"/>
</int-xml:xpath-router>

As already mentioned, the default evaluation type for XPath expressions is NODESET, which is converted to a List<String> of channel names, therefore handling single channel scenarios as well as multiple ones.

Nonetheless, certain XPath expressions may evaluate as String type from the very beginning. Take for example the following XPath Expression:

name(./node())

This expression will return the name of the root node. It will resulting in an exception, if the default evaluation type NODESET is being used.

For these scenarious, you may use the evaluate-as-string attribute, which will allow you to manage the evaluation type. It is FALSE by default, however if set to TRUE, the String evaluation type will be used.

For example if we want to route based on the name of the root node, we can use the following configuration:

<int-xml:xpath-router id="xpathRouterAsString"
        input-channel="xpathStringChannel"
        evaluate-as-string="true">
    <int-xml:xpath-expression expression="name(./node())"/>
</int-xml:xpath-router>

The XPath Header Enricher defines a Header Enricher Message Transformer that evaluates XPath expressions against the message payload and inserts the result of the evaluation into a messsage header.

Please see below for an overview of all available configuration parameters:

<int-xml:xpath-header-enricher default-overwrite="true"    
                               id=""                       
                               input-channel=""            
                               output-channel=""           
                               should-skip-nulls="true">   
    <int:poller></int:poller>                              
    <int-xml:header name=""                                
                    evaluation-type="STRING_RESULT"        
                    header-type="int"                      
                    overwrite="true"                       
                    xpath-expression=""                    
                    xpath-expression-ref=""/>              
</int-xml:xpath-header-enricher>

This component defines an XPath-based Message Filter. Under the covers this components uses a MessageFilter that wraps an instance of AbstractXPathMessageSelector.

In order to use the XPath Filter you must as a minimum provide an XPath Expression either by declaring the xpath-expression sub-element or by referencing an XPath Expression using the xpath-expression-ref attribute.

If the provided XPath expression will evaluate to a boolean value, no further configuration parameters are necessary. However, if the XPath expression will evaluate to a String, the match-value attribute should be specified against which the evaluation result will be matched.

There are three options for the match-type:

When providing a match-type value of regex, the value provided with the match-value attribute must be a valid Regular Expression.

<int-xml:xpath-filter discard-channel=""                      
                      id=""                                   
                      input-channel=""                        
                      match-type="exact"                      
                      match-value=""                          
                      output-channel=""                       
                      throw-exception-on-rejection="false"    
                      xpath-expression-ref="">                
    <int-xml:xpath-expression ... />                          
    <int:poller ... />                                        
</int-xml:xpath-filter>

Spring Integration, since version 3.0, provides the #xpath built-in SpEL function, which invokes the static method XPathUtils.evaluate(...). This method delegates to an org.springframework.xml.xpath.XPathExpression. The following shows some usage examples:

<transformer expression="#xpath(payload, '/name')"/>

<filter expression="#xpath(payload, headers.xpath, 'boolean')"/>

<splitter expression="#xpath(payload, '//book', 'document_list')"/>

<router expression="#xpath(payload, '/person/@age', 'number')">
    <mapping channel="output1" value="16"/>
    <mapping channel="output2" value="45"/>
</router>

#xpath also supports a third optional parameter for converting the result of the xpath evaluation. It can be one of the String constants 'string', 'boolean', 'number', 'node', 'node_list' and 'document_list' or an org.springframework.xml.xpath.NodeMapper instance. By default the #xpath SpEL function returns a String representation of the xpath evaluation.

For more information see Appendix A, Spring Expression Language (SpEL).

The XML Validating Filter allows you to validate incoming messages against provided schema instances. The following schema types are supported:

Messages that fail validation can either be silently dropped or they can be forwarded to a definable discard-channel. Furthermore you can configure this filter to throw an Exception in case validation fails.

Please see below for an overview of all available configuration parameters:

<int-xml:validating-filter discard-channel=""                    
                           id=""                                 
                           input-channel=""                      
                           output-channel=""                     
                           schema-location=""                    
                           schema-type="xml-schema"              
                           throw-exception-on-rejection="false"  
                           xml-validator="">                     
    <int:poller .../>                                            
</int-xml:validating-filter>