camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > XPath
Date Mon, 16 Jan 2012 13:36:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/XPath">XPath</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~raulvk">Raul Kripalani</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Enabling Saxon from Spring DSL <br>*Available as of Camel 2.10* <br> <br>Similarly to Java DSL, to enable Saxon from Spring DSL you have three options: <br> <br>Specifying the factory <br>{code:xml} <br>&lt;xpath factoryRef=&quot;saxonFactory&quot; resultType=&quot;java.lang.String&quot;&gt;current-dateTime()&lt;/xpath&gt; <br>{code} <br> <br>Specifying the object model <br>{code:xml} <br>&lt;xpath objectModel=&quot;http://saxon.sf.net/jaxp/xpath/om&quot; resultType=&quot;java.lang.String&quot;&gt;current-dateTime()&lt;/xpath&gt; <br>{code} <br> <br>Shortcut <br>{code:xml} <br>&lt;xpath saxon=&quot;true&quot; resultType=&quot;java.lang.String&quot;&gt;current-dateTime()&lt;/xpath&gt; <br>{code} <br> <br>h3. Namespace auditing to aid debugging <br>*Available as of Camel 2.10* <br> <br>A large number of XPath-related issues that users frequently face are linked to the usage of namespaces. You may have some misalignment between the namespaces present in your message and those that your XPath expression is aware of or referencing. XPath predicates or expressions that are unable to locate the XML elements and attributes due to namespaces issues may simply look like &quot;they are not working&quot;, when in reality all there is to it is a lack of namespace definition. <br> <br>Namespaces in XML are completely necessary, and while we would love to simplify their usage by implementing some magic or voodoo to wire namespaces automatically, truth is that any action down this path would disagree with the standards and would greatly hinder interoperability. <br> <br>Therefore, the utmost we can do is assist you in debugging such issues by adding two new features to the XPath Expression Language and are thus accesible from both predicates and expressions. <br> <br>h4. Logging the Namespace Context of your XPath expression/predicate <br> <br>Every time a new XPath expression is created in the internal pool, Camel will log the namespace context of the expression under the {{org.apache.camel.builder.xml.XPathBuilder}} logger. Since Camel represents Namespace Contexts in a hierarchical fashion (parent-child relationships), the entire tree is output in a recursive manner with the following format: <br> <br>{code} <br>[me: {prefix -&gt; namespace}, {prefix -&gt; namespace}], [parent: [me: {prefix -&gt; namespace}, {prefix -&gt; namespace}], [parent: [me: {prefix -&gt; namespace}]]] <br>{code} <br> <br>Any of these options can be used to activate this logging: <br># Enable TRACE logging on the {{org.apache.camel.builder.xml.XPathBuilder}} logger, or some parent logger such as {{org.apache.camel}} or the root logger <br># Enable the {{logNamespaces}} option as indicated in [Auditing Namespaces|#AuditingNamespaces], in which case the logging will occur on the INFO level <br> <br>{anchor:AuditingNamespaces} <br>h4. Auditing namespaces  <br> <br>Camel is able to discover and dump all namespaces present on every incoming message before evaluating an XPath expression, providing all the richness of information you need to help you analyse and pinpoint possible namespace issues.  <br> <br>To achieve this, it in turn internally uses another specially tailored XPath expression to extract all namespace mappings that appear in the message, displaying the prefix and the full namespace URI(s) for each individual mapping.  <br> <br>Some points to take into account: <br> <br>* The implicit XML namespace (xmlns:xml=&quot;http://www.w3.org/XML/1998/namespace&quot;) is suppressed from the output because it adds no value <br>* Default namespaces are listed under the DEFAULT keyword in the output <br>* Keep in mind that namespaces can be remapped under different scopes. Think of a top-level &#39;a&#39; prefix which in inner elements can be assigned a different namespace, or the default namespace changing in inner scopes. For each discovered prefix, all associated URIs are listed. <br> <br>You can enable this option in Java DSL and Spring DSL. <br> <br>Java DSL: <br> <br>{code:java} <br>XPathBuilder.xpath(&quot;/foo:person/@id&quot;, String.class).logNamespaces() <br>{code} <br> <br>Spring DSL: <br>{code:xml} <br>&lt;xpath logNamespaces=&quot;true&quot; resultType=&quot;String&quot;&gt;/foo:person/@id&lt;/xpath&gt; <br>{code} <br> <br>The result of the auditing will be appear at the INFO level under the {{org.apache.camel.builder.xml.XPathBuilder}} logger and will look like the following: <br> <br>{code} <br>2012-01-16 13:23:45,878 [stSaxonWithFlag] INFO  XPathBuilder  - Namespaces discovered in message: {xmlns:a=[http://apache.org/camel], DEFAULT=[http://apache.org/default],  <br>xmlns:b=[http://apache.org/camelA, http://apache.org/camelB]} <br>{code} <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. Dependencies <br>The XPath language is part of camel-core. <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="XPath-XPath"></a>XPath</h2>

<p>Camel supports <a href="http://www.w3.org/TR/xpath" class="external-link" rel="nofollow">XPath</a> to allow an <a href="/confluence/display/CAMEL/Expression" title="Expression">Expression</a> or <a href="/confluence/display/CAMEL/Predicate" title="Predicate">Predicate</a> to be used in the <a href="/confluence/display/CAMEL/DSL" title="DSL">DSL</a> or <a href="/confluence/display/CAMEL/Xml+Configuration" title="Xml Configuration">Xml Configuration</a>. For example you could use XPath to create an <a href="/confluence/display/CAMEL/Predicate" title="Predicate">Predicate</a> in a <a href="/confluence/display/CAMEL/Message+Filter" title="Message Filter">Message Filter</a> or as an <a href="/confluence/display/CAMEL/Expression" title="Expression">Expression</a> for a <a href="/confluence/display/CAMEL/Recipient+List" title="Recipient List">Recipient List</a>.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"queue:foo"</span>).
  filter().xpath(<span class="code-quote">"<span class="code-comment">//foo"</span>)).
</span>  to(<span class="code-quote">"queue:bar"</span>)
</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"queue:foo"</span>).
  choice().xpath(<span class="code-quote">"<span class="code-comment">//foo"</span>)).to(<span class="code-quote">"queue:bar"</span>).
</span>  otherwise().to(<span class="code-quote">"queue:others"</span>);
</pre>
</div></div>

<h3><a name="XPath-Namespaces"></a>Namespaces</h3>

<p>In 1.3 onwards you can easily use namespaces with XPath expressions using the Namespaces helper class.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">Namespaces ns = <span class="code-keyword">new</span> Namespaces(<span class="code-quote">"c"</span>, <span class="code-quote">"http:<span class="code-comment">//acme.com/cheese"</span>);
</span>
from(<span class="code-quote">"direct:start"</span>).filter().
        xpath(<span class="code-quote">"/c:person[@name='James']"</span>, ns).
        to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>

<h3><a name="XPath-Variables"></a>Variables</h3>

<p>Variables in XPath is defined in different namespaces. The default namespace is <tt><a href="http://camel.apache.org/schema/spring" class="external-link" rel="nofollow">http://camel.apache.org/schema/spring</a></tt>.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Namespace URI </th>
<th class='confluenceTh'> Local part </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://camel.apache.org/xml/in/" class="external-link" rel="nofollow">http://camel.apache.org/xml/in/</a> </td>
<td class='confluenceTd'> in </td>
<td class='confluenceTd'> Message </td>
<td class='confluenceTd'> the exchange.in message </td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://camel.apache.org/xml/out/" class="external-link" rel="nofollow">http://camel.apache.org/xml/out/</a> </td>
<td class='confluenceTd'>  out </td>
<td class='confluenceTd'> Message </td>
<td class='confluenceTd'> the exchange.out message </td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://camel.apache.org/xml/function/" class="external-link" rel="nofollow">http://camel.apache.org/xml/function/</a> </td>
<td class='confluenceTd'> functions </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> <b>Camel 2.5:</b> Additional functions </td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://camel.apache.org/xml/variables/environment-variables" class="external-link" rel="nofollow">http://camel.apache.org/xml/variables/environment-variables</a> </td>
<td class='confluenceTd'> env </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> OS environment variables </td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://camel.apache.org/xml/variables/system-properties" class="external-link" rel="nofollow">http://camel.apache.org/xml/variables/system-properties</a> </td>
<td class='confluenceTd'> system </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> Java System properties </td>
</tr>
<tr>
<td class='confluenceTd'> <a href="http://camel.apache.org/xml/variables/exchange-property" class="external-link" rel="nofollow">http://camel.apache.org/xml/variables/exchange-property</a> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> the exchange property </td>
</tr>
</tbody></table>
</div>


<p>Camel will resolve variables according to either:</p>
<ul class="alternate" type="square">
	<li>namespace given</li>
	<li>no namespace given</li>
</ul>


<h4><a name="XPath-Namespacegiven"></a>Namespace given</h4>
<p>If the namespace is given then Camel is instructed exactly what to return. However when resolving either <b>in</b> or <b>out</b> Camel will try to resolve a header with the given local part first, and return it. If the local part has the value <b>body</b> then the body is returned instead. </p>

<h4><a name="XPath-Nonamespacegiven"></a>No namespace given</h4>
<p>If there is no namespace given then Camel resolves only based on the local part. Camel will try to resolve a variable in the following steps:</p>
<ul class="alternate" type="square">
	<li>from <tt>variables</tt> that has been set using the <tt>variable(name, value)</tt> fluent builder</li>
	<li>from message.in.header if there is a header with the given key</li>
	<li>from exchange.properties if there is a property with the given key</li>
</ul>


<h3><a name="XPath-Functions"></a>Functions</h3>
<p>Camel adds the following XPath functions that can be used to access the exchange:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Function </th>
<th class='confluenceTh'> Argument </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> in:body </td>
<td class='confluenceTd'> none </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> Will return the <b>in</b> message body. </td>
</tr>
<tr>
<td class='confluenceTd'> in:header </td>
<td class='confluenceTd'> the header name </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> Will return the <b>in</b> message header. </td>
</tr>
<tr>
<td class='confluenceTd'> out:body </td>
<td class='confluenceTd'> none </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> Will return the <b>out</b> message body. </td>
</tr>
<tr>
<td class='confluenceTd'> out:header </td>
<td class='confluenceTd'> the header name </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> Will return the <b>out</b> message header. </td>
</tr>
<tr>
<td class='confluenceTd'> function:properties </td>
<td class='confluenceTd'> key for property </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <b>Camel 2.5:</b> To lookup a property using the <a href="/confluence/display/CAMEL/Properties" title="Properties">Properties</a> component (property placeholders). </td>
</tr>
<tr>
<td class='confluenceTd'> function:simple </td>
<td class='confluenceTd'> simple expression </td>
<td class='confluenceTd'> Object </td>
<td class='confluenceTd'> <b>Camel 2.5:</b> To evaluate a <a href="/confluence/display/CAMEL/Simple" title="Simple">Simple</a> expression. </td>
</tr>
</tbody></table>
</div>


<p><b>Notice:</b> <tt>function:properties</tt> and <tt>function:simple</tt> is not supported when the return type is a <tt>NodeSet</tt>, such as when using with a <a href="/confluence/display/CAMEL/Splitter" title="Splitter">Splitter</a> EIP.</p>

<p>Here's an example showing some of these functions in use.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"direct:start"</span>).choice()
  .when().xpath(<span class="code-quote">"in:header('foo') = 'bar'"</span>).to(<span class="code-quote">"mock:x"</span>)
  .when().xpath(<span class="code-quote">"in:body() = '&lt;two/&gt;'"</span>).to(<span class="code-quote">"mock:y"</span>)
  .otherwise().to(<span class="code-quote">"mock:z"</span>);
</pre>
</div></div>

<p>And the new functions introduced in Camel 2.5:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// setup properties component
</span>PropertiesComponent properties = <span class="code-keyword">new</span> PropertiesComponent();
properties.setLocation(<span class="code-quote">"classpath:org/apache/camel/builder/xml/myprop.properties"</span>);
context.addComponent(<span class="code-quote">"properties"</span>, properties);

<span class="code-comment">// myprop.properties contains the following properties
</span><span class="code-comment">// foo=Camel
</span><span class="code-comment">// bar=Kong
</span>
from(<span class="code-quote">"direct:in"</span>).choice()
    <span class="code-comment">// $type is a variable <span class="code-keyword">for</span> the header with key type
</span>    <span class="code-comment">// here we use the properties function to lookup foo from the properties files
</span>    <span class="code-comment">// which at runtime will be evaluted to 'Camel'
</span>    .when().xpath(<span class="code-quote">"$type = function:properties('foo')"</span>)
        .to(<span class="code-quote">"mock:camel"</span>)
    <span class="code-comment">// here we use the simple language to evaluate the expression
</span>    <span class="code-comment">// which at runtime will be evaluated to 'Donkey Kong'
</span>    .when().xpath(<span class="code-quote">"<span class="code-comment">//name = function:simple('Donkey ${properties:bar}')"</span>)
</span>        .to(<span class="code-quote">"mock:donkey"</span>)
    .otherwise()
        .to(<span class="code-quote">"mock:other"</span>)
    .end();
</pre>
</div></div>


<h3><a name="XPath-UsingXMLconfiguration"></a>Using XML configuration</h3>

<p>If you prefer to configure your routes in your <a href="/confluence/display/CAMEL/Spring" title="Spring">Spring</a> XML file then you can use XPath expressions as follows</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;beans xmlns=<span class="code-quote">"http://www.springframework.org/schema/beans"</span>
       <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance"</span>
       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"&gt;

  <span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://activemq.apache.org/camel/schema/spring"</span> <span class="code-keyword">xmlns:foo</span>=<span class="code-quote">"http://example.com/person"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
      <span class="code-tag">&lt;from uri=<span class="code-quote">"activemq:MyQueue"</span>/&gt;</span>
      <span class="code-tag">&lt;filter&gt;</span>
        <span class="code-tag">&lt;xpath&gt;</span>/foo:person[@name='James']<span class="code-tag">&lt;/xpath&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mqseries:SomeOtherQueue"</span>/&gt;</span>
      <span class="code-tag">&lt;/filter&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
  <span class="code-tag">&lt;/camelContext&gt;</span>
<span class="code-tag">&lt;/beans&gt;</span>
</pre>
</div></div>

<p>Notice how we can reuse the namespace prefixes, <b>foo</b> in this case, in the XPath expression for easier namespace based XPath expressions!</p>

<p>See also this <a href="http://camel.465427.n5.nabble.com/fail-filter-XPATH-camel-td476424.html" class="external-link" rel="nofollow">discussion on the mailinglist</a> about using your own namespaces with xpath</p>

<h3><a name="XPath-Settingresulttype"></a>Setting result type</h3>
<p>The <a href="/confluence/display/CAMEL/XPath" title="XPath">XPath</a> expression will return a result type using native XML objects such as <tt>org.w3c.dom.NodeList</tt>. But many times you want a result type to be a String. To do this you have to instruct the <a href="/confluence/display/CAMEL/XPath" title="XPath">XPath</a> which result type to use.</p>

<p>In Java DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
xpath(<span class="code-quote">"/foo:person/@id"</span>, <span class="code-object">String</span>.class)
</pre>
</div></div>

<p>In Spring DSL you use the <b>resultType</b> attribute to provide a fully qualified classname:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;xpath resultType=<span class="code-quote">"java.lang.String"</span>&gt;</span>/foo:person/@id<span class="code-tag">&lt;/xpath&gt;</span>
</pre>
</div></div>

<p>In @XPath:<br/>
<b>Available as of Camel 2.1</b></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@XPath(value = <span class="code-quote">"concat('foo-',<span class="code-comment">//order/name/)"</span>, resultType = <span class="code-object">String</span>.class) <span class="code-object">String</span> name)</span>
</pre>
</div></div>
<p>Where we use the xpath function concat to prefix the order name with <tt>foo-</tt>. In this case we have to specify that we want a String as result type so the concat function works.</p>

<h3><a name="XPath-Examples"></a>Examples</h3>

<p>Here is a simple <a href="http://svn.apache.org/repos/asf/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/XPathFilterTest.java" class="external-link" rel="nofollow">example</a> using an XPath expression as a predicate in a <a href="/confluence/display/CAMEL/Message+Filter" title="Message Filter">Message Filter</a></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"direct:start"</span>).
        filter().xpath(<span class="code-quote">"/person[@name='James']"</span>).
        to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>

<p>If you have a standard set of namespaces you wish to work with and wish to share them across many different XPath expressions you can use the NamespaceBuilder as shown <a href="http://svn.apache.org/repos/asf/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/XPathWithNamespaceBuilderFilterTest.java" class="external-link" rel="nofollow">in this example</a></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// lets define the namespaces we'll need in our filters
</span>Namespaces ns = <span class="code-keyword">new</span> Namespaces(<span class="code-quote">"c"</span>, <span class="code-quote">"http:<span class="code-comment">//acme.com/cheese"</span>)
</span>        .add(<span class="code-quote">"xsd"</span>, <span class="code-quote">"http:<span class="code-comment">//www.w3.org/2001/XMLSchema"</span>);
</span>
<span class="code-comment">// now lets create an xpath based Message Filter
</span>from(<span class="code-quote">"direct:start"</span>).
        filter(ns.xpath(<span class="code-quote">"/c:person[@name='James']"</span>)).
        to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>

<p>In this sample we have a choice construct. The first choice evaulates if the message has a header key <b>type</b> that has the value <b>Camel</b>.<br/>
The 2nd choice evaluates if the message body has a name tag <b>&lt;name&gt;</b> which values is <b>Kong</b>.<br/>
If neither is true the message is routed in the otherwise block:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"direct:in"</span>).choice()
    <span class="code-comment">// using $headerName is special notation in Camel to get the header key
</span>    .when().xpath(<span class="code-quote">"$type = 'Camel'"</span>)
        .to(<span class="code-quote">"mock:camel"</span>)
    <span class="code-comment">// here we test <span class="code-keyword">for</span> the body name tag
</span>    .when().xpath(<span class="code-quote">"<span class="code-comment">//name = 'Kong'"</span>)
</span>        .to(<span class="code-quote">"mock:donkey"</span>)
    .otherwise()
        .to(<span class="code-quote">"mock:other"</span>)
    .end();
</pre>
</div></div>

<p>And the spring XML equivalent of the route:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:in"</span>/&gt;</span>
        <span class="code-tag">&lt;choice&gt;</span>
            <span class="code-tag">&lt;when&gt;</span>
                <span class="code-tag">&lt;xpath&gt;</span>$type = 'Camel'<span class="code-tag">&lt;/xpath&gt;</span>
                <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:camel"</span>/&gt;</span>
            <span class="code-tag">&lt;/when&gt;</span>
            <span class="code-tag">&lt;when&gt;</span>
                <span class="code-tag">&lt;xpath&gt;</span>//name = 'Kong'<span class="code-tag">&lt;/xpath&gt;</span>
                <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:donkey"</span>/&gt;</span>
            <span class="code-tag">&lt;/when&gt;</span>
            <span class="code-tag">&lt;otherwise&gt;</span>
                <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:other"</span>/&gt;</span>
            <span class="code-tag">&lt;/otherwise&gt;</span>
        <span class="code-tag">&lt;/choice&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<h2><a name="XPath-XPathinjection"></a>XPath injection </h2>

<p>You can use <a href="/confluence/display/CAMEL/Bean+Integration" title="Bean Integration">Bean Integration</a> to invoke a method on a bean and use various languages such as XPath to extract a value from the message and bind it to a method parameter.</p>

<p>The default XPath annotation has SOAP and XML namespaces available. If you want to use your own namespace URIs in an XPath expression you can use your own copy of the <a href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/language/XPath.html" class="external-link" rel="nofollow">XPath annotation</a> to create whatever namespace prefixes you want to use. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">import</span> java.lang.annotation.ElementType;
<span class="code-keyword">import</span> java.lang.annotation.Retention;
<span class="code-keyword">import</span> java.lang.annotation.RetentionPolicy;
<span class="code-keyword">import</span> java.lang.annotation.Target;

<span class="code-keyword">import</span> org.w3c.dom.NodeList;

<span class="code-keyword">import</span> org.apache.camel.component.bean.XPathAnnotationExpressionFactory;
<span class="code-keyword">import</span> org.apache.camel.language.LanguageAnnotation;
<span class="code-keyword">import</span> org.apache.camel.language.NamespacePrefix;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@LanguageAnnotation(language = <span class="code-quote">"xpath"</span>, factory = XPathAnnotationExpressionFactory.class)
<span class="code-keyword">public</span> @<span class="code-keyword">interface</span> MyXPath {
    <span class="code-object">String</span> value();

    <span class="code-comment">// You can add the namespaces as the <span class="code-keyword">default</span> value of the annotation
</span>    NamespacePrefix[] namespaces() <span class="code-keyword">default</span> {
    @NamespacePrefix(prefix = <span class="code-quote">"n1"</span>, uri = <span class="code-quote">"http:<span class="code-comment">//example.org/ns1"</span>),
</span>    @NamespacePrefix(prefix = <span class="code-quote">"n2"</span>, uri = <span class="code-quote">"http:<span class="code-comment">//example.org/ns2"</span>)};
</span>
    <span class="code-object">Class</span>&lt;?&gt; resultType() <span class="code-keyword">default</span> NodeList.class;
}
</pre>
</div></div>

<p>i.e. cut and paste upper code to your own project in a different package and/or annotation name then add whatever namespace prefix/uris you want in scope when you use your annotation on a method parameter. Then when you use your annotation on a method parameter all the namespaces you want will be available for use in your XPath expression.</p>

<p><b>NOTE</b> this feature is supported from Camel 1.6.1.</p>

<p>For example</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Foo {
	
    @MessageDriven(uri = <span class="code-quote">"activemq:my.queue"</span>)
    <span class="code-keyword">public</span> void doSomething(@MyXPath(<span class="code-quote">"/ns1:foo/ns2:bar/text()"</span>) <span class="code-object">String</span> correlationID, @Body <span class="code-object">String</span> body) {
		<span class="code-comment">// process the inbound message here
</span>    }
}
</pre>
</div></div>

<h3><a name="XPath-UsingXPathBuilderwithoutanExchange"></a>Using XPathBuilder without an Exchange</h3>
<p><b>Available as of Camel 2.3</b></p>

<p>You can now use the <tt>org.apache.camel.builder.XPathBuilder</tt> without the need for an <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>. This comes handy if you want to use it as a helper to do custom xpath evaluations. </p>

<p>It requires that you pass in a <a href="/confluence/display/CAMEL/CamelContext" title="CamelContext">CamelContext</a> since a lot of the moving parts inside the XPathBuilder requires access to the Camel <a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">Type Converter</a> and hence why <a href="/confluence/display/CAMEL/CamelContext" title="CamelContext">CamelContext</a> is needed.</p>

<p>For example you can do something like this:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">boolean</span> matches = XPathBuilder.xpath(<span class="code-quote">"/foo/bar/@xyz"</span>).matches(context, <span class="code-quote">"&lt;foo&gt;&lt;bar xyz='cheese'/&gt;&lt;/foo&gt;"</span>));
</pre>
</div></div>
<p>This will match the given predicate.</p>

<p>You can also evaluate for example as shown in the following three examples:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    <span class="code-object">String</span> name = XPathBuilder.xpath(<span class="code-quote">"foo/bar"</span>).evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;cheese&lt;/bar&gt;&lt;/foo&gt;"</span>, <span class="code-object">String</span>.class);
    <span class="code-object">Integer</span> number = XPathBuilder.xpath(<span class="code-quote">"foo/bar"</span>).evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;123&lt;/bar&gt;&lt;/foo&gt;"</span>, <span class="code-object">Integer</span>.class);
    <span class="code-object">Boolean</span> bool = XPathBuilder.xpath(<span class="code-quote">"foo/bar"</span>).evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;<span class="code-keyword">true</span>&lt;/bar&gt;&lt;/foo&gt;"</span>, <span class="code-object">Boolean</span>.class);
</pre>
</div></div>

<p>Evaluating with a String result is a common requirement and thus you can do it a bit simpler:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    <span class="code-object">String</span> name = XPathBuilder.xpath(<span class="code-quote">"foo/bar"</span>).evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;cheese&lt;/bar&gt;&lt;/foo&gt;"</span>);
</pre>
</div></div>

<h3><a name="XPath-UsingSaxonwithXPathBuilder"></a>Using Saxon with XPathBuilder</h3>
<p><b>Available as of Camel 2.3</b></p>

<p>You need to add <b>camel-saxon</b> as dependency to your project.</p>

<p>Its now easier to use <a href="http://saxon.sourceforge.net/" class="external-link" rel="nofollow">Saxon</a> with the XPathBuilder which can be done in several ways as shown below.<br/>
Where as the latter ones are the easiest ones.</p>

<p>Using a factory</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// create a Saxon factory
</span>XPathFactory fac = <span class="code-keyword">new</span> net.sf.saxon.xpath.XPathFactoryImpl();

<span class="code-comment">// create a builder to evaluate the xpath using the saxon factory
</span>XPathBuilder builder = XPathBuilder.xpath(<span class="code-quote">"tokenize(/foo/bar, '_')[2]"</span>).factory(fac);

<span class="code-comment">// evaluate as a <span class="code-object">String</span> result
</span><span class="code-object">String</span> result = builder.evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;abc_def_ghi&lt;/bar&gt;&lt;/foo&gt;"</span>);
assertEquals(<span class="code-quote">"def"</span>, result);
</pre>
</div></div>

<p>Using ObjectModel</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// create a builder to evaluate the xpath using saxon based on its object model uri
</span>XPathBuilder builder = XPathBuilder.xpath(<span class="code-quote">"tokenize(/foo/bar, '_')[2]"</span>).objectModel(<span class="code-quote">"http:<span class="code-comment">//saxon.sf.net/jaxp/xpath/om"</span>);
</span>
<span class="code-comment">// evaluate as a <span class="code-object">String</span> result
</span><span class="code-object">String</span> result = builder.evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;abc_def_ghi&lt;/bar&gt;&lt;/foo&gt;"</span>);
assertEquals(<span class="code-quote">"def"</span>, result);
</pre>
</div></div>

<p>The easy one</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// create a builder to evaluate the xpath using saxon
</span>XPathBuilder builder = XPathBuilder.xpath(<span class="code-quote">"tokenize(/foo/bar, '_')[2]"</span>).saxon();

<span class="code-comment">// evaluate as a <span class="code-object">String</span> result
</span><span class="code-object">String</span> result = builder.evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;abc_def_ghi&lt;/bar&gt;&lt;/foo&gt;"</span>);
assertEquals(<span class="code-quote">"def"</span>, result);
</pre>
</div></div>

<h3><a name="XPath-SettingacustomXPathFactoryusingSystemProperty"></a>Setting a custom XPathFactory using System Property</h3>
<p><b>Available as of Camel 2.3</b></p>

<p>Camel now supports reading the <a href="http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/xpath/XPathFactory.html#newInstance(java.lang.String)" class="external-link" rel="nofollow">JVM system property <tt>javax.xml.xpath.XPathFactory</tt></a> that can be used to set a custom XPathFactory to use.</p>

<p>This unit test shows how this can be done to use Saxon instead:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// set system property with the XPath factory to use which is Saxon 
</span><span class="code-object">System</span>.setProperty(XPathFactory.DEFAULT_PROPERTY_NAME + <span class="code-quote">":"</span> + <span class="code-quote">"http:<span class="code-comment">//saxon.sf.net/jaxp/xpath/om"</span>, <span class="code-quote">"net.sf.saxon.xpath.XPathFactoryImpl"</span>);
</span>
<span class="code-comment">// create a builder to evaluate the xpath using saxon
</span>XPathBuilder builder = XPathBuilder.xpath(<span class="code-quote">"tokenize(/foo/bar, '_')[2]"</span>);

<span class="code-comment">// evaluate as a <span class="code-object">String</span> result
</span><span class="code-object">String</span> result = builder.evaluate(context, <span class="code-quote">"&lt;foo&gt;&lt;bar&gt;abc_def_ghi&lt;/bar&gt;&lt;/foo&gt;"</span>);
assertEquals(<span class="code-quote">"def"</span>, result);
</pre>
</div></div>

<p>Camel will log at <tt>INFO</tt> level if it uses a non default XPathFactory such as:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
XPathBuilder  INFO  Using system property javax.xml.xpath.XPathFactory:http:<span class="code-comment">//saxon.sf.net/jaxp/xpath/om with value:
</span>                    net.sf.saxon.xpath.XPathFactoryImpl when creating XPathFactory
</pre>
</div></div>

<h3><a name="XPath-EnablingSaxonfromSpringDSL"></a>Enabling Saxon from Spring DSL</h3>
<p><b>Available as of Camel 2.10</b></p>

<p>Similarly to Java DSL, to enable Saxon from Spring DSL you have three options:</p>

<p>Specifying the factory</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;xpath factoryRef=<span class="code-quote">"saxonFactory"</span> resultType=<span class="code-quote">"java.lang.String"</span>&gt;</span>current-dateTime()<span class="code-tag">&lt;/xpath&gt;</span>
</pre>
</div></div>

<p>Specifying the object model</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;xpath objectModel=<span class="code-quote">"http://saxon.sf.net/jaxp/xpath/om"</span> resultType=<span class="code-quote">"java.lang.String"</span>&gt;</span>current-dateTime()<span class="code-tag">&lt;/xpath&gt;</span>
</pre>
</div></div>

<p>Shortcut</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;xpath saxon=<span class="code-quote">"true"</span> resultType=<span class="code-quote">"java.lang.String"</span>&gt;</span>current-dateTime()<span class="code-tag">&lt;/xpath&gt;</span>
</pre>
</div></div>

<h3><a name="XPath-Namespaceauditingtoaiddebugging"></a>Namespace auditing to aid debugging</h3>
<p><b>Available as of Camel 2.10</b></p>

<p>A large number of XPath-related issues that users frequently face are linked to the usage of namespaces. You may have some misalignment between the namespaces present in your message and those that your XPath expression is aware of or referencing. XPath predicates or expressions that are unable to locate the XML elements and attributes due to namespaces issues may simply look like "they are not working", when in reality all there is to it is a lack of namespace definition.</p>

<p>Namespaces in XML are completely necessary, and while we would love to simplify their usage by implementing some magic or voodoo to wire namespaces automatically, truth is that any action down this path would disagree with the standards and would greatly hinder interoperability.</p>

<p>Therefore, the utmost we can do is assist you in debugging such issues by adding two new features to the XPath Expression Language and are thus accesible from both predicates and expressions.</p>

<h4><a name="XPath-LoggingtheNamespaceContextofyourXPathexpression%2Fpredicate"></a>Logging the Namespace Context of your XPath expression/predicate</h4>

<p>Every time a new XPath expression is created in the internal pool, Camel will log the namespace context of the expression under the <tt>org.apache.camel.builder.xml.XPathBuilder</tt> logger. Since Camel represents Namespace Contexts in a hierarchical fashion (parent-child relationships), the entire tree is output in a recursive manner with the following format:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
[me: {prefix -&gt; namespace}, {prefix -&gt; namespace}], [parent: [me: {prefix -&gt; namespace}, {prefix -&gt; namespace}], [parent: [me: {prefix -&gt; namespace}]]]
</pre>
</div></div>

<p>Any of these options can be used to activate this logging:</p>
<ol>
	<li>Enable TRACE logging on the <tt>org.apache.camel.builder.xml.XPathBuilder</tt> logger, or some parent logger such as <tt>org.apache.camel</tt> or the root logger</li>
	<li>Enable the <tt>logNamespaces</tt> option as indicated in <a href="#XPath-AuditingNamespaces">Auditing Namespaces</a>, in which case the logging will occur on the INFO level</li>
</ol>


<p><a name="XPath-AuditingNamespaces"></a></p>
<h4><a name="XPath-Auditingnamespaces"></a>Auditing namespaces </h4>

<p>Camel is able to discover and dump all namespaces present on every incoming message before evaluating an XPath expression, providing all the richness of information you need to help you analyse and pinpoint possible namespace issues. </p>

<p>To achieve this, it in turn internally uses another specially tailored XPath expression to extract all namespace mappings that appear in the message, displaying the prefix and the full namespace URI(s) for each individual mapping. </p>

<p>Some points to take into account:</p>

<ul>
	<li>The implicit XML namespace (xmlns:xml="http://www.w3.org/XML/1998/namespace") is suppressed from the output because it adds no value</li>
	<li>Default namespaces are listed under the DEFAULT keyword in the output</li>
	<li>Keep in mind that namespaces can be remapped under different scopes. Think of a top-level 'a' prefix which in inner elements can be assigned a different namespace, or the default namespace changing in inner scopes. For each discovered prefix, all associated URIs are listed.</li>
</ul>


<p>You can enable this option in Java DSL and Spring DSL.</p>

<p>Java DSL:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
XPathBuilder.xpath(<span class="code-quote">"/foo:person/@id"</span>, <span class="code-object">String</span>.class).logNamespaces()
</pre>
</div></div>

<p>Spring DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;xpath logNamespaces=<span class="code-quote">"true"</span> resultType=<span class="code-quote">"String"</span>&gt;</span>/foo:person/@id<span class="code-tag">&lt;/xpath&gt;</span>
</pre>
</div></div>

<p>The result of the auditing will be appear at the INFO level under the <tt>org.apache.camel.builder.xml.XPathBuilder</tt> logger and will look like the following:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
2012-01-16 13:23:45,878 [stSaxonWithFlag] INFO  XPathBuilder  - Namespaces discovered in message: {xmlns:a=[http:<span class="code-comment">//apache.org/camel], DEFAULT=[http://apache.org/<span class="code-keyword">default</span>], 
</span>xmlns:b=[http:<span class="code-comment">//apache.org/camelA, http://apache.org/camelB]}</span>
</pre>
</div></div>

<h3><a name="XPath-Dependencies"></a>Dependencies</h3>
<p>The XPath language is part of camel-core.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/XPath">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=53132&revisedVersion=49&originalVersion=48">View Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/XPath?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message