Page History

h2. XQuery

Camel supports [XQuery|http://www.w3.org/TR/xquery/] to allow an [Expression] or [Predicate] to be used in the [DSL] or [Xml Configuration]. For example you could use XQuery to create an [Predicate] in a [Message Filter] or as an [Expression] for a [Recipient List].

h3. Options
{div:class=confluenceTableSmall}
|| Name || Default Value || Description ||
| {{allowStAX}} | {{false}} | *Camel 2.8.3/2.9:* Whether to allow using StAX as the {{javax.xml.transform.Source}}. |
{div}

h3. Examples

{code}
from("queue:foo").filter().
  xquery("//foo").
  to("queue:bar")
{code}

You can also use functions inside your query, in which case you need an explicit type conversion (or you will get a org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR) by passing the Class as a second argument to the *xquery()* method.

{code}
from("direct:start").
  recipientList().xquery("concat('mock:foo.', /person/@city)", String.class);
{code}

h3. Variables

The IN message body will be set as the {{contextItem}}. Besides this these Variables is also added as parameters:

|| Variable || Type || Description || Support version ||
| exchange | Exchange | The current Exchange | |
| in.body | Object | The In message's body  |  >= 1.6.1 |
| out.body | Object | The OUT message's body (if any)| >= 1.6.1 |
| in.headers.*| Object | You can access the value of exchange.in.headers with key *foo* by using the variable which name is in.headers.foo| >=1.6.1 |
| out.headers.* | Object | You can access the value of exchange.out.headers with key *foo* by using the variable which name is out.headers.foo variable| >=1.6.1 |
| *key name* | Object | Any exchange.properties and exchange.in.headers (exchange.in.headers support was removed since camel 1.6.1) and any additional parameters set using {{setParameters(Map)}}. These parameters is added with they own key name, for instance if there is an IN header with the key name *foo* then its added as *foo*. | |

h3. Using XML configuration

If you prefer to configure your routes in your [Spring] XML file then you can use XPath expressions as follows

{code:lang=xml}
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:foo="http://example.com/person"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

  <camelContext id="camel" xmlns="http://activemq.apache.org/camel/schema/spring">
    <route>
      <from uri="activemq:MyQueue"/>
      <filter>
        <xquery>/foo:person[@name='James']</xquery>
        <to uri="mqseries:SomeOtherQueue"/>
      </filter>
    </route>
  </camelContext>
</beans>
{code}

Notice how we can reuse the namespace prefixes, *foo* in this case, in the XPath expression for easier namespace based XQuery expressions!

When you use functions in your XQuery expression you need an explicit type conversion which is done in the xml configuration via the *@type* attribute: 

{code:lang=xml}
    <xquery type="java.lang.String">concat('mock:foo.', /person/@city)</xquery>
{code}

h3. Using XQuery as an endpoint

Sometimes an XQuery expression can be quite large; it can essentally be used for [Templating]. So you may want to use an [XQuery Endpoint] so you can route using XQuery templates.

The following example shows how to take a message of an ActiveMQ queue (MyQueue) and transform it using XQuery and send it to MQSeries.

{code}
  <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="activemq:MyQueue"/>
      <to uri="xquery:com/acme/someTransform.xquery"/>
      <to uri="mqseries:SomeOtherQueue"/>
    </route>
  </camelContext>
{code}

h3. Examples

Here is a simple [example|http://svn.apache.org/repos/asf/camel/trunk/components/camel-saxon/src/test/java/org/apache/camel/builder/saxon/XQueryFilterTest.java] using an XQuery expression as a predicate in a [Message Filter]

{snippet:id=example|lang=java|url=camel/trunk/components/camel-saxon/src/test/java/org/apache/camel/builder/saxon/XQueryFilterTest.java}

This [example|http://svn.apache.org/repos/asf/camel/trunk/components/camel-saxon/src/test/java/org/apache/camel/builder/saxon/XQueryWithNamespacesFilterTest.java] uses XQuery with namespaces as a predicate in a [Message Filter]

{snippet:id=example|lang=java|url=camel/trunk/components/camel-saxon/src/test/java/org/apache/camel/builder/saxon/XQueryWithNamespacesFilterTest.java}

h3. Learning XQuery

XQuery is a very powerful language for querying, searching, sorting and returning XML. For help learning XQuery try these tutorials

* Mike Kay's [XQuery Primer|http://www.stylusstudio.com/xquery_primer.html]
* the W3Schools [XQuery Tutorial|http://www.w3schools.com/xquery/default.asp]

You might also find the [XQuery function reference|http://www.w3.org/TR/xpath-functions/] useful

h3. Dependencies

To use XQuery in your camel routes you need to add the a dependency on *camel-saxon* which implements the XQuery language. 

If you use maven you could just add the following to your pom.xml, substituting the version number for the latest & greatest release (see [the download page for the latest versions|Download]).

{code}
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-saxon</artifactId>
  <version>1<version>x.4x.0<x</version>
</dependency>
{code}