Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

XML Module Reference

The XML module contains several tools to help you read, transform, and write XML.

In addition to the functionality described on this page, you can also use the SXC Module Reference, which enables efficient XPath XML routing.

Supported XPath, XQuery, and XSLT Versions

In 2013, the World Wide Web Consortium (W3C) published a new spec for version 3.0 of the XPath XQuery and XSLT standards. The new version of the standards is at "last call" status, and therefore highly unlikely to undergo major changes.

Mule 3.6.0 provides basic support for version 3.0 of the standards. "Basic support" means that any feature of the specification is supported as long as it doesn’t rely on schema awareness, high order functions, or streaming.

Mule 3.6.0 also provides improved support for XPath 2.0, XSLT 2.0, and XQuery 1.0.

We recommend upgrading from Mule 3.5 to 3.6.x to take advantage of these features.

Important Changes in Mule 3.6.0

The table below lists supported versions of the standards and their related components in Mule 3.6.0.

Component Version Supported Changes in Mule 3.6.0

XPath

1

No

Deprecated in 3.6.0 (supported until Mule 4.0):*

  • xpath2() function, superseded by the xpath3() function

  • JXPath extractor

  • JXPath filter

  • Jaxen filter

New function: xpath3(), which includes improved return type handling. For details, see XPath.

2

yes

3

Yes

XML Formats

Mule understands a wide variety of XML Java representations:

  • org.w3c.dom.Document, org.w3c.dom.Element

  • org.dom4j.Document

  • javax.xml.transform.Source

  • InputStream, String, byte[]

  • OutputHandler

  • XMLStreamReader

  • org.mule.module.xml.transformer.DelayedResult

Any transformer that accepts XML as an input also understands these types.

Transformers

There are several standard transformers that process XML inside Mule.

Transformer Description

XmlToObject to ObjectToXml

Converts XML to a Java object and back again using XStream.

JAXB XmlToObject to JAXB ObjectToXml

Converts XML to a Java object and back again using the JAXB binding framework (ships with JDK6)

XSLT

Transforms XML payloads using XSLT.

XQuery

Transforms XML payloads using XQuery.

DomToXml to XmlToDom

Converts DOM objects to XML and back again.

XmlToXMLStreamReader

Converts XML from a message payload to a StAX XMLStreamReader.

XPath Extractor

Queries and extracts object graphs using XPath expressions using JAXP.

JXPath Extractor *Deprecated*

Queries and extracts object graphs using XPath expressions using JXPath. Deprecated in favor of the xpath3() function (see 3.6 XPath).

XmlPrettyPrinter

Allows you to output the XML with controlled formatting, including trimming white space and specifying the indent.

Efficient Transformations with DelayedResult

Mule contains a special XML output format called DelayedResult. This format allows very efficient XML transformations by delaying any XML serialization until an OutputStream is available.

For example, here is an XSLT transformer set up to use DelayedResult:


          
       
1
2
3
<mxml:xslt-transformer name="transform-in"
      xsl-file="xslt/transform.xslt"
      returnClass="org.mule.module.xml.transformer.DelayedResult"/>

If the result of this transformation were being sent to an HTTP client, the HTTP client would ask Mule for an OutputHandler and pass in the OutputStream to it. Only then would Mule perform the transformation, writing the output directly to the OutputStream.

If DelayedResult were not used, the XML result would first be written to an in-memory buffer before being written to the OutputStream. This will cause your XML processing to be slower.

Filters

The XML module contains various XPath filters. For general details on how to use filters, see Filters.

XPath Filter

Mule 3.6.0 and later versions support XPath 3.0, which is backwards-compatible with XPath 2.0. On the other hand, XPath 1.0 is deprecated, and while simple expressions may work, some expressions may be incompatible. For details, see Mule 3.6 XPath.

The XPath filter uses the JAXP libraries to filter XPath expressions.

The following configuration routes messages to the "vm://echo" endpoint when the value of "/e:purchaseOrder/e:shipTo/@country" is "US".


          
       
1
2
3
4
5
6
7
8
9
<outbound>
  <filtering-router>
    <outbound-endpoint address="vm://echo" synchronous="true"/>
    <mule-xml:xpath-filter pattern="/e:purchaseOrder/e:shipTo/@country" expectedValue="US">
      <mule-xml:namespace prefix="e" uri="http://www.example.com"/>
    </mule-xml:xpath-filter>
  </filtering-router>
....
</outbound>

Schema Validation Filter

The schema validation filter uses the JAXP libraries to validate your message against a schema. 

The following configuration validates your message against a schema called schema.xsd and a schema called anotherSchema.xsd.


          
       
1
<mule-xml:schema-validation-filter schemaLocations="com/myapp/schemas/schema.xsd, com/myapp/schemas/anotherSchema.xsd"/>

Jaxen Filter

*Deprecated*

In Mule 3.6.0, the Jaxen filter will be deprecated, but is kept for backwards compatibility only. Instead, it is recommended to use the new function xpath3, which provides improved XPath support.

For a detailed description of the xpath3 function, see XPath.

The Jaxen filter uses the Jaxen library to filter messages based on XPath expressions.

The following configuration routes messages to the "vm://echo" endpoint when the value of "/e:purchaseOrder/e:shipTo/@country" is "US".


          
       
1
2
3
4
5
6
7
8
9
<outbound>
  <filtering-router>
    <outbound-endpoint address="vm://echo" synchronous="true"/>
    <mule-xml:jaxen-filter pattern="/e:purchaseOrder/e:shipTo/@country" expectedValue="US">
      <mule-xml:namespace prefix="e" uri="http://www.example.com"/>
    </mule-xml:jaxen-filter>
  </filtering-router>
....
</outbound>

JXPath Filter

*Deprecated*

In Mule 3.6.0, the JXPath filter will be deprecated, but is kept for backwards compatibility only. Instead, it is recommended to use the new function xpath3, which provides improved XPath support.

For a detailed description of the xpath3 function, see XPath.

The JXPath filter is very similar to the Jaxen filter. It is still used for historical purposes (it existed before the Jaxen filter).


          
       
1
2
3
4
5
6
7
8
9
10
<outbound>
    <filtering-router>
        <outbound-endpoint address="vm://echo" synchronous="true"/>
        <mule-xml:jxpath-filter pattern="/e:purchaseOrder/e:shipTo/@country"
                            expectedValue="US">
            <mule-xml:namespace prefix="e" uri="http://www.example.com"/>
        </mule-xml:jxpath-filter>
    </filtering-router>
....
</outbound>

Splitters

The XML module contains two splitters, a filter-based splitter and a round-robin splitter.

XML Parsers

In most cases, SAX is used to parse your XML. If you use CXF or the XmlToXMLStreamReader, use StAX instead. For more information, see the Jenkov Java SAX vs StAX site.

If you’re using SAX, the SAX XML parser is determined by your JVM. If you want to change your SAX implementation, see the Sax Project Quickstart.