xpath3(xpath_expression, input_data, return_type)
XPath
Mule 3.6.0 and above
Supported XPath Versions
Mule 3.6.0 and newer 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 newer also provide improved support for XPath 2.0, XSLT 2.0 and XQuery 1.0.
Mule 3.6.0 and newer 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 is only supported until Mule 4.0.
In Mule 3.6.0, the following XPath components were 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 works 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 and Query Parameters.
The function takes the following form:
Function Parameters
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 causes 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 ajava.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 ajava.lang.String
. Equivalent to wrapping the expression in a call to the XPathstring()
function. -
NUMBER
: Returns the result of the expression converted to a double as ajava.lang.Double
. Equivalent to wrapping the expression in a call of the XPathnumber()
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‐variable variableName="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 is available on XPath evaluation.
The example below shows how to perform an XPath evaluation on a document with multiple namespaces.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body foo="bar">
<ns1:echo xmlns: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-manager includeConfigNamespaces="true">
<mulexml:namespace prefix="soap" uri="http://schemas.xmlsoap.org/soap/envelope/"/>
<mulexml:namespace prefix="mule" uri="http://simple.component.mule.org/"/>
</mulexml:namespace-manager>
<flowname="xpathWithNamespace">
<expression‐transformer expression="xpath3('/soap:Envelope/soap:Body/mule:echo/mule:echo')"/>
</flow>
To ensure consistency, namespace support has also been added to the xpath3('/*:/contacts/') |
XQuery
The xquery-transformer element retains the same syntax as in previous versions. You can select the XQuery version using xquery version in the XQuery script, as shown below:
<mxml:xquery‐text>
<![CDATA[
xquery version "3.0";
XQuery 3.0 introduces support for several new features in the XQuery transformer, such as using an XQuery script to operate on multiple documents at once. For more information, see XQuery Transformer.