Contact Us 1-800-596-4880
  1. Homepage
  2. XML Module (0.3.6)

  3. XPath

All Connectors

XPath

_*Mule 3.6.0 and above*_

Supported XPath Versions

Mule 3.6.0 and later provide basic support for version 3.0 of the spec. This means that any feature of the spec is supported as long as it doesn’t rely on schema awareness, high order functions, or streaming.

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

Mule 3.6.0 and later include the xpath3() `function which provides full support for XPath 3.0 and 2.0. However, versions 3.0 and 2.0 are not fully compatible with version 1.0; for this reason, the old `xpath() function will be supported until Mule 4.0.

In Mule 3.6.0, the following XPath components have been deprecated:

  • xpath expression evaluator

  • xpath2 expression evaluator

  • bean expression evaluator

  • jxpath filter

  • jxpath extractor transformer

  • jaxen filter

Since XPath 3.0 is completely backwards-compatible with XPath 2.0, the new function will work for 2.0 expressions as well. XPath 1.0 expressions, however, are not guaranteed to work. Compatibility mode is limited, and disabled by default.

For a description of the new xpath3() function, see the next section.

The xpath3() Function

The xpath3() function supports function parameters including the ability to select the return type for obtained data, and query parameters.

The function takes the following form:

xpath3(xpath_expression, input_data, return_type)

Function Parameters

XPath Expression (String, Required)

The XPath expression to evaluate. Cannot be null or blank.

Input Data (Object, Optional)

If not provided, this defaults to the message payload. It supports the following input types:

  • org.w3c.dom.Document

  • org.w3c.dom.Node

  • org.xml.sax.InputSource

  • OutputHandler

  • byte[]

  • InputStream

  • String

  • XMLStreamReader

  • DelayedResult

If input is not of any of the above types, the function attempts to use a registered transformer to transform the input into a DOM document or node. If no such transformer is found, then an IllegalArgumentException is thrown.

Additionally, this function verifies if the input is of a consumable type, such as streams or readers. Evaluating the expression over a consumable input will cause the input source to be exhausted, so in cases in which the input value was the actual message payload (whether left blank by the user or provided by default), the function updates the output message payload with the result obtained from consuming the input.

Return Type (String, Optional)

If not provided, defaults to String.

This parameter was introduced to allow for the different intents you may have when invoking the xpath3() function, such as retrieving the actual data or just verifying if a specific node exists. This feature conforms to the JAXP API JSR-206, which defines the standard way for a Java application to handle XML, and therefore to execute XPath expressions. This parameter allows you to leverage this feature of the JAXP API without delving into the API’s complexities.

You can select from the following list of possible output types:

  • BOOLEAN: Returns the effective boolean value of the expression as a java.lang.String. Equivalent to wrapping the expression in a call of the XPath `boolean() ` function.

  • STRING: Returns the result of the expression converted to a string, as a java.lang.String. Equivalent to wrapping the expression in a call to the XPath string() function.

  • NUMBER: Returns the result of the expression converted to a double as a java.lang.Double. Equivalent to wrapping the expression in a call of the XPath number() function.

  • NODE: Returns the result as a node object.

  • NODESET: Returns a DOM NodeList object.

Query Parameters

The xpath3() function supports passing parameters into the XPath query. The example below shows a query which returns all the LINE elements which contain a given word:

//LINE[contains(., $word)]

The $ sign marks the parameter. The function automatically resolves that variable against the current flow variables. The example below returns all occurrences of the word "handkerchief:"

<set‐variablevariableName="word"value="handkerchief"/>
<expression‐transformer>
   xpath3('//LINE[contains(.,$word)]',payload,'NODESET')
</expression‐transformer>

Namespace Manager

The xpath3() function is namespace-manager-aware, which means that all namespaces configured through a namespace-manager component will be available on XPath evaluation.

The example below shows how to perform an XPath evaluation on a document with multiple namespaces.

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Bodyfoo="bar">
  <ns1:echoxmlns:ns1="http://simple.component.mule.org/">
    <ns1:echo>Hello!</ns1:echo>
  </ns1:echo>
</soap:Body> </soap:Envelope>

The above sample document has several namespaces, which the Xpath engine needs to be aware of in order to navigate the DOM tree. The relevant xpath3() function is shown below.

<mulexml:namespace‐managerincludeConfigNamespaces="true">
  <mulexml:namespaceprefix="soap"uri="http://schemas.xmlsoap.org/soap/envelope/"/>
  <mulexml:namespaceprefix="mule"uri="http://simple.component.mule.org/"/>
</mulexml:namespace‐manager>

<flowname="xpathWithNamespace">
  <expression‐transformerexpression="xpath3('/soap:Envelope/soap:Body/mule:echo/mule:echo')"/>
</flow>
To ensure consistency, namespace support has also been added to the xquery-transformer element. For this reason, some applications may have issues if they use expressions with custom namespaces without correctly specifying the namespace manager. You can avoid this issue by declaring the namespace manager or using a wildcard, for example using * instead of the namespace, as shown below. 
xpath3('/*:/contacts/')