The XQuery Module gives users the ability to perform XQuery transformations on XML messages in Mule. This works in a very similar way to the XSLT Transformer shipped with Mule.
Mule 3.6.0 and later versions include XQuery 3.0 support for the XQuery transformer. The transformer’s behavior and syntax remain unaltered, and you can declare the version to use in the XQuery script itself (see below). For details on XML, XSLT, Xquery, and XPath support in Mule, see the XPath guide.
If the XQuery version is not declared, the transformer defaults to version 1.0. Version 3.0 is backwards-compatible and per the spec, all queries in 1.0 are valid in 3.0 and must return the same result.
To select the XQuery version to use, you can include it in the XQuery script, as shown below:
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 3.0 below.
To use the XQuery transformer you need to add it to your Mule Xml configuration
Here we are configuring a transformer using in-line XQuery expressions.
We also define two
These properties are pulled from the current message and made available in the XQuery context so that they can be referenced in your XQuery statements. These can be object references or you can use Mule Expressions to get information from the current message.
Now your configured XQuery transformer can be referenced by an endpoint. In the following example, you can drop and XML file into a directory on the local machine (see the inbound file endpoint) and the result will be written to
The test data looks like this:
The result written to
System.out looks like:
The full configuration for this examples looks like:
Mule 3.6.0 introduces support for XQuery 3.0 . The XQuery transformer’s behavior and syntax remain unaltered, and you can declare the version to use in the XQuery script itself (see above).
Support for version 3.0 introduces some new features and improvements which are described in the following sections.
Mule 3.6.0 introduces support for passing DOM documents and nodes (instances of
org.w3c.dom.Node). The following simple query takes two XML files (one listing cities, the other listing books) and mixes the title of the book with the name of the city. The
$books variables are passed as context properties.
Another possibility with XQuery 3.0 is to provide the path to the actual XML document, in which case the engine generates the document itself. In this case, the flow variables only contain the path to the XML documents on disk, and the
fn:doc function inside the query does the parsing.
You can now use
try … Catch blocks in your XQuery statements. This simple example shows a script which always fails and consistently returns an error tag.
XQuery 3.0 also introduces the
group by clause, shown below:
The above script returns the following:
Prior to Mule 3.6.0, the results returned by the XQuery transformer had several drawbacks:
By default, the transformer only returned the first result (unless the
returnClassattribute was set to an array)
If the user specified a return value but no results were found, the transformer returned
If only one result was found, the transformer returned that one element, even if it was configured to return an array
As of Mule 3.6.0, the default behavior has changed:
By default, the transformer returns a Java List
The list contains all results, even if only one was found
If no results are found, the list is empty
If you specify a return class, then the transformer falls back to the old behavior (array, one element, or null).