XQuery Support
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.
Declaring the XQuery Version
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.
Configuration
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 <context-property> elements:
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.
Example
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 System.out.
The test data looks like this:
The result written to System.out looks like:
The full configuration for this examples looks like:
XQuery 3.0
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.
Operating on Multiple Inputs
Mule 3.6.0 introduces support for passing DOM documents and nodes (instances of org.w3c.dom.Document or 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 $cities and $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.
try… Catch Blocks
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.
Group By
XQuery 3.0 also introduces the group by clause, shown below:
The above script returns the following:
Return Type Improvements
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
NullPayload -
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).