camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > Content Enricher
Date Thu, 21 Mar 2013 09:56: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/Content+Enricher">Content
Enricher</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~davsclaus">Claus
Ibsen</a>
    </h4>
        <br/>
                         <h4>Changes (4)</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" >| {{ref}} | | Refers to the endpoint
for the external service to enrich from. You must use either {{uri}} or {{ref}}. | <br>|
{{strategyRef}} | | Refers to an [AggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html]
to be used to merge the reply from the external service, into a single outgoing message. By
default Camel will use the reply from the external service as outgoing message. | <br></td></tr>
            <tr><td class="diff-changed-lines" >| {{timeout}} | <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{{0}}</span>
<span class="diff-added-words"style="background-color: #dfd;">{{-1}}</span> |
Timeout in millis when polling from the external service. See below for important details
about the timeout. | <br></td></tr>
            <tr><td class="diff-unchanged" >{div} <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{info:title=Good
practice to use timeout value} <br>By default Camel will use the {{receive}}. Which
may block until there is a message available. It is therefore recommended to always provide
a timeout value, to make this clear that we may wait for a message, until the timeout is hit.
<br>{info} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">By
default Camel will use the {{receiveNoWait}}.  <br></td></tr>
            <tr><td class="diff-unchanged" >If there is no data then the {{newExchange}}
in the aggregation strategy is {{null}}.  <br> <br>You can pass in a timeout value
that determines which method to use <br></td></tr>
            <tr><td class="diff-changed-lines" >- if timeout is -1 or other negative
number then {{receive}} is selected <span class="diff-added-words"style="background-color:
#dfd;">(*Important:* the {{receive}} method may block if there is no message)</span>
<br></td></tr>
            <tr><td class="diff-unchanged" >- if timeout is 0 then {{receiveNoWait}}
is selected <br>- otherwise {{receive(timeout)}} is selected <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h3><a name="ContentEnricher-ContentEnricher"></a>Content Enricher</h3>

<p>Camel supports the <a href="http://www.enterpriseintegrationpatterns.com/DataEnricher.html"
class="external-link" rel="nofollow">Content Enricher</a> from the <a href="/confluence/display/CAMEL/Enterprise+Integration+Patterns"
title="Enterprise Integration Patterns">EIP patterns</a> using a <a href="/confluence/display/CAMEL/Message+Translator"
title="Message Translator">Message Translator</a>, an arbitrary <a href="/confluence/display/CAMEL/Processor"
title="Processor">Processor</a> in the routing logic, or using the <a href="#ContentEnricher-enrichdsl">enrich</a>
DSL element to enrich the message.</p>

<p><span class="image-wrap" style=""><img src="http://www.enterpriseintegrationpatterns.com/img/DataEnricher.gif"
style="border: 0px solid black" /></span></p>

<h4><a name="ContentEnricher-ContentenrichmentusingaMessageTranslatororaProcessor"></a>Content
enrichment using a Message Translator or a Processor</h4>

<p><b>Using the</b> <b><a href="/confluence/display/CAMEL/Fluent+Builders"
title="Fluent Builders">Fluent Builders</a></b></p>

<p>You can use <a href="/confluence/display/CAMEL/Templating" title="Templating">Templating</a>
to consume a message from one destination, transform it with something like <a href="/confluence/display/CAMEL/Velocity"
title="Velocity">Velocity</a> or <a href="/confluence/display/CAMEL/XQuery" title="XQuery">XQuery</a>,
and then send it on to another destination. For example using InOnly (one way messaging)</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  to(<span class="code-quote">"velocity:com/acme/MyResponse.vm"</span>).
  to(<span class="code-quote">"activemq:Another.Queue"</span>);
</pre>
</div></div>
<p>If you want to use InOut (request-reply) semantics to process requests on the <b>My.Queue</b>
queue on <a href="/confluence/display/CAMEL/ActiveMQ" title="ActiveMQ">ActiveMQ</a>
with a template generated response, then sending responses back to the JMSReplyTo Destination
you could use this:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  to(<span class="code-quote">"velocity:com/acme/MyResponse.vm"</span>);
</pre>
</div></div>
<p>Here is a simple example using the <a href="/confluence/display/CAMEL/DSL" title="DSL">DSL</a>
directly to transform the message body</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>).setBody(body().append(<span
class="code-quote">" World!"</span>)).to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>
<p>In this example we add our own <a href="/confluence/display/CAMEL/Processor" title="Processor">Processor</a>
using explicit Java code</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>).process(<span
class="code-keyword">new</span> Processor() {
    <span class="code-keyword">public</span> void process(Exchange exchange) {
        Message in = exchange.getIn();
        in.setBody(in.getBody(<span class="code-object">String</span>.class) +
<span class="code-quote">" World!"</span>);
    }
}).to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>
<p>Finally we can use <a href="/confluence/display/CAMEL/Bean+Integration" title="Bean
Integration">Bean Integration</a> to use any Java method on any bean to act as the
transformer</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  beanRef(<span class="code-quote">"myBeanName"</span>, <span class="code-quote">"myMethodName"</span>).
  to(<span class="code-quote">"activemq:Another.Queue"</span>);
</pre>
</div></div>
<p>For further examples of this pattern in use you could look at one of the JUnit tests</p>
<ul>
	<li><a href="http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/TransformTest.java?view=markup"
class="external-link" rel="nofollow">TransformTest</a></li>
	<li><a href="http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/TransformViaDSLTest.java?view=markup"
class="external-link" rel="nofollow">TransformViaDSLTest</a></li>
</ul>


<p><b>Using Spring XML</b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;route&gt;
  &lt;from uri=<span class="code-quote">"activemq:Input"</span>/&gt;
  &lt;bean ref=<span class="code-quote">"myBeanName"</span> method=<span
class="code-quote">"doTransform"</span>/&gt;
  &lt;to uri=<span class="code-quote">"activemq:Output"</span>/&gt;
&lt;/route&gt;
</pre>
</div></div>

<p><a name="ContentEnricher-enrichdsl"></a></p>
<h3><a name="ContentEnricher-Contentenrichmentusingthe%7B%7Benrich%7D%7DDSLelement"></a>Content
enrichment using the <tt>enrich</tt> DSL element</h3>

<p>Camel comes with two flavors of content enricher in the DSL</p>
<ul class="alternate" type="square">
	<li><tt>enrich</tt></li>
	<li><tt>pollEnrich</tt></li>
</ul>


<p><tt>enrich</tt> uses a <tt>Producer</tt> to obtain the additional
data. It is usually used for <a href="/confluence/display/CAMEL/Request+Reply" title="Request
Reply">Request Reply</a> messaging, for instance to invoke an external web service.<br/>
<tt>pollEnrich</tt> on the other hand uses a <a href="/confluence/display/CAMEL/Polling+Consumer"
title="Polling Consumer">Polling Consumer</a> to obtain the additional data. It is
usually used for <a href="/confluence/display/CAMEL/Event+Message" title="Event Message">Event
Message</a> messaging, for instance to read a file or download a <a href="/confluence/display/CAMEL/FTP2"
title="FTP2">FTP</a> file.</p>

<h3><a name="ContentEnricher-EnrichOptions"></a>Enrich Options</h3>

<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>uri</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> The endpoint uri for the external service to enrich from.
You must use either <tt>uri</tt> or <tt>ref</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ref</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Refers to the endpoint for the external service to enrich
from. You must use either <tt>uri</tt> or <tt>ref</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>strategyRef</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Refers to an <a href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html"
class="external-link" rel="nofollow">AggregationStrategy</a> to be used to merge
the reply from the external service, into a single outgoing message. By default Camel will
use the reply from the external service as outgoing message. </td>
</tr>
</tbody></table>
</div>
</div>


<p><b>Using the</b> <b><a href="/confluence/display/CAMEL/Fluent+Builders"
title="Fluent Builders">Fluent Builders</a></b></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
AggregationStrategy aggregationStrategy = ...

from(<span class="code-quote">"direct:start"</span>)
.enrich(<span class="code-quote">"direct:resource"</span>, aggregationStrategy)
.to(<span class="code-quote">"direct:result"</span>);

from(<span class="code-quote">"direct:resource"</span>)
...
</pre>
</div></div>

<p>The content enricher (<tt>enrich</tt>) retrieves additional data from
a <em>resource endpoint</em> in order to enrich an incoming message (contained
in the <em>original exchange</em>). An aggregation strategy is used to combine
the original exchange and the <em>resource exchange</em>. The first parameter
of the <tt>AggregationStrategy.aggregate(Exchange, Exchange)</tt> method corresponds
to the the original exchange, the second parameter the resource exchange. The results from
the resource endpoint are stored in the resource exchange's out-message. Here's an example
template for implementing an aggregation strategy:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class ExampleAggregationStrategy <span
class="code-keyword">implements</span> AggregationStrategy {

    <span class="code-keyword">public</span> Exchange aggregate(Exchange original,
Exchange resource) {
        <span class="code-object">Object</span> originalBody = original.getIn().getBody();
        <span class="code-object">Object</span> resourceResponse = resource.getIn().getBody();
        <span class="code-object">Object</span> mergeResult = ... <span class="code-comment">//
combine original body and resource response
</span>        <span class="code-keyword">if</span> (original.getPattern().isOutCapable())
{
            original.getOut().setBody(mergeResult);
        } <span class="code-keyword">else</span> {
            original.getIn().setBody(mergeResult);
        }
        <span class="code-keyword">return</span> original;
    }
    
}
</pre>
</div></div>

<p>Using this template the original exchange can be of any pattern. The resource exchange
created by the enricher is always an in-out exchange.</p>

<p><b>Using Spring XML</b></p>

<p>The same example in the Spring DSL</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span>
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:start"</span>/&gt;</span>
    <span class="code-tag">&lt;enrich uri=<span class="code-quote">"direct:resource"</span>
strategyRef=<span class="code-quote">"aggregationStrategy"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"direct:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:resource"</span>/&gt;</span>
    ...
  <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>

<span class="code-tag">&lt;bean id=<span class="code-quote">"aggregationStrategy"</span>
class=<span class="code-quote">"..."</span> /&gt;</span>
</pre>
</div></div>

<h4><a name="ContentEnricher-Aggregationstrategyisoptional"></a>Aggregation
strategy is optional</h4>
<p>The aggregation strategy is optional. If you do not provide it Camel will by default
just use the body obtained from the resource.</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>)
  .enrich(<span class="code-quote">"direct:resource"</span>)
  .to(<span class="code-quote">"direct:result"</span>);
</pre>
</div></div>
<p>In the route above the message sent to the <tt>direct:result</tt> endpoint
will contain the output from the <tt>direct:resource</tt> as we do not use any
custom aggregation.</p>

<p>And for Spring DSL just omit the <tt>strategyRef</tt> attribute:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
    <span class="code-tag">&lt;enrich uri=<span class="code-quote">"direct:resource"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"direct:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>

<h3><a name="ContentEnricher-Contentenrichmentusing%7B%7BpollEnrich%7D%7D"></a>Content
enrichment using <tt>pollEnrich</tt></h3>
<p>The <tt>pollEnrich</tt> works just as the <tt>enrich</tt>
however as it uses a <a href="/confluence/display/CAMEL/Polling+Consumer" title="Polling
Consumer">Polling Consumer</a> we have 3 methods when polling</p>
<ul class="alternate" type="square">
	<li>receive</li>
	<li>receiveNoWait</li>
	<li>receive(timeout)</li>
</ul>


<h3><a name="ContentEnricher-PollEnrichOptions"></a>PollEnrich Options</h3>

<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>uri</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> The endpoint uri for the external service to enrich from.
You must use either <tt>uri</tt> or <tt>ref</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ref</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Refers to the endpoint for the external service to enrich
from. You must use either <tt>uri</tt> or <tt>ref</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>strategyRef</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Refers to an <a href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html"
class="external-link" rel="nofollow">AggregationStrategy</a> to be used to merge
the reply from the external service, into a single outgoing message. By default Camel will
use the reply from the external service as outgoing message. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>timeout</tt> </td>
<td class='confluenceTd'> <tt>-1</tt> </td>
<td class='confluenceTd'> Timeout in millis when polling from the external service.
See below for important details about the timeout. </td>
</tr>
</tbody></table>
</div>
</div>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Good practice
to use timeout value</b><br />By default Camel will use the <tt>receive</tt>.
Which may block until there is a message available. It is therefore recommended to always
provide a timeout value, to make this clear that we may wait for a message, until the timeout
is hit.</td></tr></table></div>

<p>If there is no data then the <tt>newExchange</tt> in the aggregation
strategy is <tt>null</tt>. </p>

<p>You can pass in a timeout value that determines which method to use</p>
<ul class="alternate" type="square">
	<li>if timeout is -1 or other negative number then <tt>receive</tt> is
selected (<b>Important:</b> the <tt>receive</tt> method may block
if there is no message)</li>
	<li>if timeout is 0 then <tt>receiveNoWait</tt> is selected</li>
	<li>otherwise <tt>receive(timeout)</tt> is selected</li>
</ul>


<p>The timeout values is in millis.</p>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Data from
current Exchange not used</b><br /><tt>pollEnrich</tt> does <b>not</b>
access any data from the current <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>
which means when polling it cannot use any of the existing headers you may have set on the
<a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>. For
example you cannot set a filename in the <tt>Exchange.FILE_NAME</tt> header and
use <tt>pollEnrich</tt> to consume only that file. For that you <b>must</b>
set the filename in the endpoint URI.</td></tr></table></div>

<h4><a name="ContentEnricher-Example"></a>Example</h4>

<p>In this example we enrich the message by loading the content from the file named
inbox/data.txt. </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>)
  .pollEnrich(<span class="code-quote">"file:inbox?fileName=data.txt"</span>)
  .to(<span class="code-quote">"direct:result"</span>);
</pre>
</div></div>

<p>And in XML DSL you do:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
    <span class="code-tag">&lt;pollEnrich uri=<span class="code-quote">"file:inbox?fileName=data.txt"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"direct:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>

<p>If there is no file then the message is empty. We can use a timeout to either wait
(potentially forever) until a file exists, or use a timeout to wait a certain period.</p>

<p>For example to wait up to 5 seconds you can do:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
    <span class="code-tag">&lt;pollEnrich uri=<span class="code-quote">"file:inbox?fileName=data.txt"</span>
timeout=<span class="code-quote">"5000"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"direct:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>


<h4><a name="ContentEnricher-UsingThisPattern"></a>Using This Pattern</h4>

<p>If you would like to use this EIP Pattern then please read the <a href="/confluence/display/CAMEL/Getting+Started"
title="Getting Started">Getting Started</a>, you may also find the <a href="/confluence/display/CAMEL/Architecture"
title="Architecture">Architecture</a> useful particularly the description of <a
href="/confluence/display/CAMEL/Endpoint" title="Endpoint">Endpoint</a> and <a
href="/confluence/display/CAMEL/URIs" title="URIs">URIs</a>. Then you could try out
some of the <a href="/confluence/display/CAMEL/Examples" title="Examples">Examples</a>
first before trying this pattern out.</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/Content+Enricher">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=52525&revisedVersion=19&originalVersion=18">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/Content+Enricher?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message