camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > Using getIn or getOut methods on Exchange
Date Wed, 06 Oct 2010 05:37:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/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/Using+getIn+or+getOut+methods+on+Exchange">Using
getIn or getOut methods on Exchange</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~davsclaus">Claus
Ibsen</a>
    </h4>
        <br/>
                         <h4>Changes (10)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-unchanged" >h2. Using getIn or getOut methods
on Exchange <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The
Camel API is influenced by the [JBI specification|http://en.wikipedia.org/wiki/Java_Business_Integration]
which defines a concept called Message Exchange Patterns (MEP for short). The MEP defines
the messaging style used such as one-way ([InOnly|Event Message]) or request-reply ([InOut|Request
Reply]). <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
Camel API is influenced by APIs such as [JBI specification|http://en.wikipedia.org/wiki/Java_Business_Integration],
[CXF|http://cxf.apache.org/] which defines a concept called Message Exchange Patterns (MEP
for short). The MEP defines the messaging style used such as one-way ([InOnly|Event Message])
or request-reply ([InOut|Request Reply]), which means you have IN and optionally OUT messages.
This closely maps to other APIs such as WS, WSDL, REST, JBI and the likes. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >The <span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">[</span>Exchange<span
class="diff-added-chars"style="background-color: #dfd;">]</span></span> API
provides two methods to get a message, either {{getIn}} or {{getOut}}. <span class="diff-added-words"style="background-color:
#dfd;">Obviously the {{getIn}} gets the IN message, and the {{getOut}} gets the OUT message.</span>
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{info:title=Important
for Camel end users} <br>As a Camel end user you should *always* prefer to use the {{getIn}}
method, and frankly just forget about the {{getOut}} method. <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;">The
{{getOut}} method is only needed in special use cases and by certain Camel component such
as the [JBI] or [NMR] components. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Now
suppose you want to use a Camel [Processor] to adjust a message. This can be done as follows:
<br>{code:java} <br>public void process(Exchange exchange) throws Exception {
<br>   String body = exchange.getIn().getBody(String.class); <br>   // change
the message to say Hello <br>   exchange.getOut().setBody(&quot;Hello &quot;
+ body); <br>} <br>{code} <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;">If
you use the {{getOut}} method, then data from the in message would be lost. For example several
Camel end users who got started with Camel, couldn&#39;t understand why their message
headers was lost during route in Camel. The problem was they used {{getOut}} method in a Camel
[Processor]. They should as said use the {{getIn}} method. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">This
seems intuitive and is what you would expect is the _right_ approach to change a message from
a [Processor]. <br>However there is an big issue - the {{getOut}} method will create
a new [Message], which means any other information <br>from the IN message will not
be propagated; which means you will lose that data. To remedy this we&#39;ll have to copy
the data <br>which is done as follows: <br>{code:java} <br>public void process(Exchange
exchange) throws Exception { <br>   String body = exchange.getIn().getBody(String.class);
<br>   // change the message to say Hello <br>   exchange.getOut().setBody(&quot;Hello
&quot; + body); <br>   // copy headers from IN to OUT to propagate them <br>
  exchange.getOut().setHeaders(exchange.getIn().getHeaders(); <br>} <br>{code}
<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;">If
you decide to use the {{getOut}} method and want to keep headers, attachments and the likes,
then you must manually copy those information from the in to the out message. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Well
that is not all, a [Message] can also contain attachments so to be sure you need to propagate
those as well: <br>{code:java} <br>public void process(Exchange exchange) throws
Exception { <br>   String body = exchange.getIn().getBody(String.class); <br>
  // change the message to say Hello <br>   exchange.getOut().setBody(&quot;Hello
&quot; + body); <br>   // copy headers from IN to OUT to propagate them <br>
  exchange.getOut().setHeaders(exchange.getIn().getHeaders(); <br>   // copy attachements
from IN to OUT to propagate them <br>   exchange.getOut().setAttachments(exchange.getIn().getAttachments());
<br>} <br>{code} <br> <br>Now we ensure that all additional data is
propagated on the new OUT message. But its a shame we need 2 code lines to ensure data is
propagated. <br>What you can do instead is to change the IN message instead, as shown
below: <br>{code:java} <br>public void process(Exchange exchange) throws Exception
{ <br>   String body = exchange.getIn().getBody(String.class); <br>   // change
the existing message to say Hello <br>   exchange.getIn().setBody(&quot;Hello &quot;
+ body); <br>} <br>{code} <br> <br>{tip:title=Consider using getIn}
<br>As shown above you most often need to alter the existing IN message, than creating
a totally new OUT message. And therefore it&#39;s often easier just to adjust the IN message
directly. <br>{tip} <br> <br> <br>h3. About Message Exchange Pattern
and getOut <br> <br>If the [Exchange] is using {{InOnly}} as the MEP, then you
may think that the [Exchange] has no OUT message. But you can still invoke the {{getOut}}
method on [Exchange]; Camel will not barf. So the example code above is possible for any kind
of MEP. The MEP is _just_ a flag on the [Exchange] which the Consumer and Producer adhere
to. You can change the MEP on the [Exchange] using the {{setPattern}} method. And likewise
there is DSL to change it as well. <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h2><a name="UsinggetInorgetOutmethodsonExchange-UsinggetInorgetOutmethodsonExchange"></a>Using
getIn or getOut methods on Exchange</h2>

<p>The Camel API is influenced by APIs such as <a href="http://en.wikipedia.org/wiki/Java_Business_Integration"
class="external-link" rel="nofollow">JBI specification</a>, <a href="http://cxf.apache.org/"
class="external-link" rel="nofollow">CXF</a> which defines a concept called Message
Exchange Patterns (MEP for short). The MEP defines the messaging style used such as one-way
(<a href="/confluence/display/CAMEL/Event+Message" title="Event Message">InOnly</a>)
or request-reply (<a href="/confluence/display/CAMEL/Request+Reply" title="Request Reply">InOut</a>),
which means you have IN and optionally OUT messages. This closely maps to other APIs such
as WS, WSDL, REST, JBI and the likes.</p>

<p>The <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>
API provides two methods to get a message, either <tt>getIn</tt> or <tt>getOut</tt>.
Obviously the <tt>getIn</tt> gets the IN message, and the <tt>getOut</tt>
gets the OUT message.</p>

<p>Now suppose you want to use a Camel <a href="/confluence/display/CAMEL/Processor"
title="Processor">Processor</a> to adjust a message. This can be done as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void process(Exchange exchange) <span
class="code-keyword">throws</span> Exception {
   <span class="code-object">String</span> body = exchange.getIn().getBody(<span
class="code-object">String</span>.class);
   <span class="code-comment">// change the message to say Hello
</span>   exchange.getOut().setBody(<span class="code-quote">"Hello "</span>
+ body);
}
</pre>
</div></div>

<p>This seems intuitive and is what you would expect is the <em>right</em>
approach to change a message from a <a href="/confluence/display/CAMEL/Processor" title="Processor">Processor</a>.<br/>
However there is an big issue - the <tt>getOut</tt> method will create a new <a
href="/confluence/display/CAMEL/Message" title="Message">Message</a>, which means
any other information<br/>
from the IN message will not be propagated; which means you will lose that data. To remedy
this we'll have to copy the data<br/>
which is done as follows:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void process(Exchange exchange) <span
class="code-keyword">throws</span> Exception {
   <span class="code-object">String</span> body = exchange.getIn().getBody(<span
class="code-object">String</span>.class);
   <span class="code-comment">// change the message to say Hello
</span>   exchange.getOut().setBody(<span class="code-quote">"Hello "</span>
+ body);
   <span class="code-comment">// copy headers from IN to OUT to propagate them
</span>   exchange.getOut().setHeaders(exchange.getIn().getHeaders();
}
</pre>
</div></div>

<p>Well that is not all, a <a href="/confluence/display/CAMEL/Message" title="Message">Message</a>
can also contain attachments so to be sure you need to propagate those as well:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void process(Exchange exchange) <span
class="code-keyword">throws</span> Exception {
   <span class="code-object">String</span> body = exchange.getIn().getBody(<span
class="code-object">String</span>.class);
   <span class="code-comment">// change the message to say Hello
</span>   exchange.getOut().setBody(<span class="code-quote">"Hello "</span>
+ body);
   <span class="code-comment">// copy headers from IN to OUT to propagate them
</span>   exchange.getOut().setHeaders(exchange.getIn().getHeaders();
   <span class="code-comment">// copy attachements from IN to OUT to propagate them
</span>   exchange.getOut().setAttachments(exchange.getIn().getAttachments());
}
</pre>
</div></div>

<p>Now we ensure that all additional data is propagated on the new OUT message. But
its a shame we need 2 code lines to ensure data is propagated.<br/>
What you can do instead is to change the IN message instead, as shown below:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void process(Exchange exchange) <span
class="code-keyword">throws</span> Exception {
   <span class="code-object">String</span> body = exchange.getIn().getBody(<span
class="code-object">String</span>.class);
   <span class="code-comment">// change the existing message to say Hello
</span>   exchange.getIn().setBody(<span class="code-quote">"Hello "</span>
+ body);
}
</pre>
</div></div>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>Consider using getIn</b><br
/>As shown above you most often need to alter the existing IN message, than creating a
totally new OUT message. And therefore it's often easier just to adjust the IN message directly.</td></tr></table></div>


<h3><a name="UsinggetInorgetOutmethodsonExchange-AboutMessageExchangePatternandgetOut"></a>About
Message Exchange Pattern and getOut</h3>

<p>If the <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>
is using <tt>InOnly</tt> as the MEP, then you may think that the <a href="/confluence/display/CAMEL/Exchange"
title="Exchange">Exchange</a> has no OUT message. But you can still invoke the <tt>getOut</tt>
method on <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>;
Camel will not barf. So the example code above is possible for any kind of MEP. The MEP is
<em>just</em> a flag on the <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a>
which the Consumer and Producer adhere to. You can change the MEP on the <a href="/confluence/display/CAMEL/Exchange"
title="Exchange">Exchange</a> using the <tt>setPattern</tt> method. And
likewise there is DSL to change it as well.</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/Using+getIn+or+getOut+methods+on+Exchange">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=23338837&revisedVersion=3&originalVersion=2">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/Using+getIn+or+getOut+methods+on+Exchange?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message