camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r999996 [1/4] - in /websites/production/camel/content: ./ cache/
Date Thu, 27 Oct 2016 17:23:23 GMT
Author: buildbot
Date: Thu Oct 27 17:23:22 2016
New Revision: 999996

Log:
Production update by buildbot for camel

Modified:
    websites/production/camel/content/async.html
    websites/production/camel/content/book-component-appendix.html
    websites/production/camel/content/book-in-one-page.html
    websites/production/camel/content/book-tutorials.html
    websites/production/camel/content/cache/main.pageCache
    websites/production/camel/content/camel-jmx.html
    websites/production/camel/content/console-example.html
    websites/production/camel/content/debugger.html
    websites/production/camel/content/pojo-messaging-example.html
    websites/production/camel/content/route-throttling-example.html
    websites/production/camel/content/siteindex.html
    websites/production/camel/content/tracer-example.html
    websites/production/camel/content/tutorial-jmsremoting.html

Modified: websites/production/camel/content/async.html
==============================================================================
--- websites/production/camel/content/async.html (original)
+++ websites/production/camel/content/async.html Thu Oct 27 17:23:22 2016
@@ -86,7 +86,7 @@
 	<tbody>
         <tr>
         <td valign="top" width="100%">
-<div class="wiki-content maincontent"><h2 id="Async-Async">Async</h2><p><strong>Available
as of Camel 2.0</strong></p><p>The asynchronous API in Camel have been rewritten
for Camel 2.0, and the information on this page applies for Camel 2.0 and later.</p><p>The
<a shape="rect" href="async.html">Async</a> API in Camel is primarily divided
in two areas<br clear="none"> 1. Initiating an <a shape="rect" href="async.html">Async</a>
messaging from the client<br clear="none"> 2. Turning a route into <a shape="rect"
href="async.html">Async</a> using the <strong>threads</strong> <a
shape="rect" href="dsl.html">DSL</a></p><p>Before we look at these two
areas we start with a bit of background information and looks at the concept from at a higher
level using diagrams.<br clear="none"> Then we check out the first area how a client
can initiate an <a shape="rect" href="async.html">Async</a> message exchange and
we also throw in the synchronous message exchange in the mix as well so we can compare
  and distill the difference.<br clear="none"> And finally we turn our attention towards
the last area the new <strong>threads</strong> DSL and what it can be used for.</p><h2
id="Async-Background">Background</h2><p>The new <a shape="rect" href="async.html">Async</a>
API in Camel 2.0 leverages in much greater detail the Java Concurrency API and its support
for executing tasks asynchronous.<br clear="none"> Therefore the Camel <a shape="rect"
href="async.html">Async</a> API should be familiar for users with knowledge of the
Java Concurrency API.</p><h3 id="Async-Afewconceptstomaster">A few concepts to
master</h3><p>When doing messaging there are a few aspects to keep in mind.</p><p>First
of all a caller can initiate a message exchange as either:</p><ul class="alternate"><li><a
shape="rect" href="event-message.html">Request only</a></li><li><a
shape="rect" href="request-reply.html">Request Reply</a></li></ul><p><a
shape="rect" href="event-message.html">Request only</a> is when the call
 er sends a message but do <strong>not</strong> expect any reply. This is also
known as fire and forget or event message.</p><p>The <a shape="rect" href="request-reply.html">Request
Reply</a> is when the caller sends a message and then <strong>waits for a reply</strong>.
This is like the <a shape="rect" href="http.html">HTTP</a> protocol that we use
every day when we surf the web.<br clear="none"> We send a request to fetch a web page
and wait until the reply message comes with the web content.</p><p>In Camel a
message is labeled with a Message <a shape="rect" href="exchange-pattern.html">Exchange
Pattern</a> that labels whether its a request only or request reply message. Camel uses
the <a shape="rect" href="jbi.html">JBI</a> term for this an uses <code>InOnly</code>
for the request only, and <code>InOut</code> for the request reply.</p><p>For
all message exchange they can be executed either:</p><ul class="alternate"><li>synchronous</li><li>asynchronous</li></ul><h4
id="Async-Synchr
 onousRequestReply">Synchronous Request Reply</h4><p>A synchronous exchange
is defined as the caller sends a message and waits until its complete before continuing. This
is illustrated in the diagram below:</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image" src="async.data/camel_sync_request_reply.png" data-image-src="/confluence/download/attachments/117116/camel_sync_request_reply.png?version=1&amp;modificationDate=1241917552000&amp;api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="10641" data-linked-resource-version="1"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_sync_request_reply.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="49"></span></p><p>1.
The client sends a sync <a shape="rect" href="request-reply.html">Request Reply</a>
message over <a shape
 ="rect" href="http.html">HTTP</a> to Camel. The client application will wait for
the response that Camel routes and processes.<br clear="none"> 2. The message invokes
an external <a shape="rect" href="mina.html">TCP</a> service using synchronous
<a shape="rect" href="request-reply.html">Request Reply</a>. The client application
still waits for the response.<br clear="none"> 3. The response is send back to the client.</p><h4
id="Async-AsynchronousRequestReply">Asynchronous Request Reply</h4><p>On the
other hand the asynchronous version is where the caller sends a message to an <a shape="rect"
href="endpoint.html">Endpoint</a> and then returns immediately back to the caller.
The message however is processed in another thread, the asynchronous thread. Then the caller
can continue doing other work and at the same time the asynchronous thread is processing the
message. This is illustrated in the diagram below:</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-em
 bedded-image" src="async.data/camel_async_request_reply.png" data-image-src="/confluence/download/attachments/117116/camel_async_request_reply.png?version=2&amp;modificationDate=1241928088000&amp;api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="10640" data-linked-resource-version="2"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_async_request_reply.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="49"></span></p><p>1.
The client sends an <a shape="rect" href="async.html">Async</a> <a shape="rect"
href="request-reply.html">Request Reply</a> message over <a shape="rect" href="http.html">HTTP</a>
to Camel. The control is immediately returned to the client application, that can continue
and do other work while Camel routes the message.<br clear="none"> 2. Camel invokes
an external <a shape="rect" href
 ="mina.html">TCP</a> service using synchronous <a shape="rect" href="request-reply.html">Request
Reply</a>. The client application can do other work simultaneously.<br clear="none">
3. The client wants to get the reply so it uses the Future handle it got as <em>response</em>
from step 1. With this handle it retrieves the reply, wait if nessasary if the reply is not
ready.</p><h3 id="Async-SynchronousRequestOnly">Synchronous Request Only</h3><p>You
can also do synchronous <a shape="rect" href="event-message.html">Request only</a>
with Camel. The client sends a message to Camel in which a reply is not expected. However
the client still waits until the message is processed completely. This is illustrated in the
diagram below:</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image" src="async.data/camel_sync_request_only.png" data-image-src="/confluence/download/attachments/117116/camel_sync_request_only.png?version=1&amp;modificationDate=124192363700
 0&amp;api=v2" data-unresolved-comment-count="0" data-linked-resource-id="10642" data-linked-resource-version="1"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_sync_request_only.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="49"></span></p><p>1.
The client sends a <a shape="rect" href="event-message.html">Request only</a>
and we can still use <a shape="rect" href="http.html">HTTP</a> despite http being
<a shape="rect" href="request-reply.html">Request Reply</a> by nature.<br clear="none">
2. Camel invokes an external <a shape="rect" href="mina.html">TCP</a> service
using synchronous <a shape="rect" href="request-reply.html">Request Reply</a>.
The client application is still waiting.<br clear="none"> 3. The message is processed
completely and the control is returned to the client.</p><p>So why do you want
to use s
 ynchronous <a shape="rect" href="event-message.html">Request Only</a>? Well if
you want to know whether the message was processed successfully or not before continuing.
With synchronous it allows you to wait while the message is being processed. In case the processing
was succesful the control is returned to the client with no notion of error. In case of failure
the client can detect this as an exception is thrown. (and <code>exchange.isFailed()</code>
returns <code>true</code>).</p><h3 id="Async-AsynchronousRequestOnly">Asynchronous
Request Only</h3><p>As opposed to the synchronous <a shape="rect" href="event-message.html">Request
Only</a> the <a shape="rect" href="async.html">Async</a> counter part will
<strong>not</strong> wait for the processing of the message to complete. In this
case the client can immediately continue doing other work while the message is being routed
and processed in Camel. This is illustrated in the diagram below:</p><p><span
class="confluence-embedded-file
 -wrapper"><img class="confluence-embedded-image" src="async.data/camel_async_request_only.png"
data-image-src="/confluence/download/attachments/117116/camel_async_request_only.png?version=1&amp;modificationDate=1241928107000&amp;api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="10644" data-linked-resource-version="1"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_async_request_only.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="49"></span></p><p>1.
The client sends a <a shape="rect" href="event-message.html">Request only</a>
and we can still use <a shape="rect" href="http.html">HTTP</a> despite http being
<a shape="rect" href="request-reply.html">Request Reply</a> by nature. The control
is immediately returned to the client application, that can continue and do other work while
Camel routes the m
 essage.<br clear="none"> 2. Camel invokes an external <a shape="rect" href="mina.html">TCP</a>
service using synchronous <a shape="rect" href="request-reply.html">Request Reply</a>.
The client application can do other work simultaneously.<br clear="none"> 3. The message
completes but no result is returned to the client.</p><p><strong>Notice:</strong>
As Camel always returns a <code>Future</code> handle for <a shape="rect" href="async.html">Async</a>
messaging to the client. The client can use this handler to get hold of the status of the
processing whether the task is complete or an Exception occured during processing. Note that
the client is not required to do so, its perfect valid to just ignore the Future handle.</p><div
class="confluence-information-macro confluence-information-macro-tip"><span class="aui-icon
aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>In case you want to know whether the
<a sha
 pe="rect" href="async.html">Async</a> <a shape="rect" href="event-message.html">Request
Only</a> failed, then you can use the <code>Future</code> handle and invoke
<code>get()</code> and if it throws a <code>ExecutionException</code>
then the processing failed. The caused exception is wrapped. You can invoke <code>isDone()</code>
first to test whether the task is done or still in progress. Otherwise invoking <code>get()</code>
will wait until the task is done.</p></div></div><p>With these diagrams
in mind lets turn out attention to the <a shape="rect" href="async.html">Async</a>
API and how to use it with Camel.</p><h2 id="Async-1)TheClientAPI">1) The <a
shape="rect" href="async.html">Async</a> Client API</h2><p>Camel provides
the <a shape="rect" href="async.html">Async</a> Client API in the <a shape="rect"
class="external-link" href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/ProducerTemplate.html">ProducerTemplate</a>
where we have added about 10 new
  methods to Camel 2.0. We have listed the most important in the table below:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Method</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Returns</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>setExecutorService</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>void</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Is used to set the Java ExecutorService. Camel
will by default provide a ScheduledExecutorService with 5 thread in the pool.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncSend</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Exchange&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Is used to send an async exchange
to a Camel <a shape="rect" href="endpoint.html">Endpoint</
 a>. Camel will imeddiately return control to the caller thread after the task has been
submitted to the executor service. This allows you to do other work while Camel processes
the exchange in the other async thread.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>asyncSendBody</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>As above but for sending body only.
This is a request only messaging style so no reply is expected. Uses the <code>InOnly</code>
exchange pattern.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>asyncRequestBody</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>As above but for sending body only. This is a
<a shape="rect" href="request-reply.html">Request Reply</a> messaging style so
a reply is expected. Uses the <code>InOut</code> exchange
  pattern.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>extractFutureBody</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>T</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Is used to get the result from the asynchronous
thread using the Java Concurrency Future handle.</p></td></tr></tbody></table></div><p>The
<code>asyncSend</code> and <code>asyncRequest</code> methods return
a Future handle. This handle is what the caller must use later to retrieve the asynchronous
response. You can do this by using the <code>extractFutureBody</code> method,
or just use plain Java but invoke <code>get()</code> on the <code>Future</code>
handle.</p><h3 id="Async-TheClientAPIwithcallbacks">The <a shape="rect" href="async.html">Async</a>
Client API with callbacks</h3><p>In addition to the Client API from above Camel
provides a variation that uses <a shape="rect" href="oncompletion.html">callbacks</a>
when the message <a shape="rect" href="exchange.html">E
 xchange</a> is done.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th
colspan="1" rowspan="1" class="confluenceTh"><p>Method</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Returns</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncCallback</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Exchange&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>In addition a callback is passed
in as a parameter using the <code>org.apache.camel.spi.Synchronization</code>
Callback. The callback is invoked when the message exchange is done.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncCallbackSendBody</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>As above but for sending body only.
This is a request only messaging s
 tyle so no reply is expected. Uses the <code>InOnly</code> exchange pattern.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncCallbackRequestBody</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>As above but for sending body only.
This is a <a shape="rect" href="request-reply.html">Request Reply</a> messaging
style so a reply is expected. Uses the <code>InOut</code> exchange pattern.</p></td></tr></tbody></table></div><p>These
methods also returns the Future handle in case you need them. The difference is that they
invokes the callback as well when the <a shape="rect" href="exchange.html">Exchange</a>
is done being routed.</p><h4 id="Async-TheFutureAPI">The Future API</h4><p>The
<code>java.util.concurrent.Future</code> API have among others the following methods:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="co
 nfluenceTh"><p>Method</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Returns</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>isDone</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>boolean</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Returns a boolean whether the task
is done or not. Will even return <code>true</code> if the tasks failed due to
an exception thrown.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>get()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Object</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Gets the response of the task. In case of an exception was
thrown the <code>java.util.concurrent.ExecutionException</code> is thrown with
the caused exception.</p></td></tr></tbody></table></div><h3
id="Async-Example:AsynchronousRequestReply">Example: Asynchronous Request Reply</h3><p>Suppose
w
 e want to call a <a shape="rect" href="http.html">HTTP</a> service but it is
usually slow and thus we do not want to block and wait for the response, as we can do other
important computation. So we can initiate an <a shape="rect" href="async.html">Async</a>
exchange to the <a shape="rect" href="http.html">HTTP</a> endpoint and then do
other stuff while the slow <a shape="rect" href="http.html">HTTP</a> service is
processing our request. And then a bit later we can use the <code>Future</code>
handle to get the response from the <a shape="rect" href="http.html">HTTP</a>
service. Yeah nice so lets do it:</p><p>First we define some routes in Camel.
One for the <a shape="rect" href="http.html">HTTP</a> service where we simulate
a slow server as it takes at least 1 second to reply. And then other route that we want to
invoke while the <a shape="rect" href="http.html">HTTP</a> service is on route.
This allows you to be able to process the two routes simultaneously:</p><div class="code
pane
 l pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<div class="wiki-content maincontent"><h2 id="Async-Async">Async</h2><p><strong>Available
as of Camel 2.0</strong></p><p>The asynchronous API in Camel have been rewritten
for Camel 2.0, and the information on this page applies for Camel 2.0 and later.</p><p>The
<a shape="rect" href="async.html">Async</a> API in Camel is primarily divided
in two areas<br clear="none"> 1. Initiating an <a shape="rect" href="async.html">Async</a>
messaging from the client<br clear="none"> 2. Turning a route into <a shape="rect"
href="async.html">Async</a> using the <strong>threads</strong> <a
shape="rect" href="dsl.html">DSL</a></p><p>Before we look at these two
areas we start with a bit of background information and looks at the concept from at a higher
level using diagrams.<br clear="none"> Then we check out the first area how a client
can initiate an <a shape="rect" href="async.html">Async</a> message exchange and
we also throw in the synchronous message exchange in the mix as well so we can compare
  and distill the difference.<br clear="none"> And finally we turn our attention towards
the last area the new <strong>threads</strong> DSL and what it can be used for.</p><h2
id="Async-Background">Background</h2><p>The new <a shape="rect" href="async.html">Async</a>
API in Camel 2.0 leverages in much greater detail the Java Concurrency API and its support
for executing tasks asynchronous.<br clear="none"> Therefore the Camel <a shape="rect"
href="async.html">Async</a> API should be familiar for users with knowledge of the
Java Concurrency API.</p><h3 id="Async-Afewconceptstomaster">A few concepts to
master</h3><p>When doing messaging there are a few aspects to keep in mind.</p><p>First
of all a caller can initiate a message exchange as either:</p><ul class="alternate"><li><a
shape="rect" href="event-message.html">Request only</a></li><li><a
shape="rect" href="request-reply.html">Request Reply</a></li></ul><p><a
shape="rect" href="event-message.html">Request only</a> is when the call
 er sends a message but do <strong>not</strong> expect any reply. This is also
known as fire and forget or event message.</p><p>The <a shape="rect" href="request-reply.html">Request
Reply</a> is when the caller sends a message and then <strong>waits for a reply</strong>.
This is like the <a shape="rect" href="http.html">HTTP</a> protocol that we use
every day when we surf the web.<br clear="none"> We send a request to fetch a web page
and wait until the reply message comes with the web content.</p><p>In Camel a
message is labeled with a Message <a shape="rect" href="exchange-pattern.html">Exchange
Pattern</a> that labels whether its a request only or request reply message. Camel uses
the <a shape="rect" href="jbi.html">JBI</a> term for this an uses <code>InOnly</code>
for the request only, and <code>InOut</code> for the request reply.</p><p>For
all message exchange they can be executed either:</p><ul class="alternate"><li>synchronous</li><li>asynchronous</li></ul><h4
id="Async-Synchr
 onousRequestReply">Synchronous Request Reply</h4><p>A synchronous exchange
is defined as the caller sends a message and waits until its complete before continuing. This
is illustrated in the diagram below:</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image" src="async.data/camel_sync_request_reply.png" data-image-src="/confluence/download/attachments/117116/camel_sync_request_reply.png?version=1&amp;modificationDate=1241917552000&amp;api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="10641" data-linked-resource-version="1"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_sync_request_reply.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="50"></span></p><p>1.
The client sends a sync <a shape="rect" href="request-reply.html">Request Reply</a>
message over <a shape
 ="rect" href="http.html">HTTP</a> to Camel. The client application will wait for
the response that Camel routes and processes.<br clear="none"> 2. The message invokes
an external <a shape="rect" href="mina.html">TCP</a> service using synchronous
<a shape="rect" href="request-reply.html">Request Reply</a>. The client application
still waits for the response.<br clear="none"> 3. The response is send back to the client.</p><h4
id="Async-AsynchronousRequestReply">Asynchronous Request Reply</h4><p>On the
other hand the asynchronous version is where the caller sends a message to an <a shape="rect"
href="endpoint.html">Endpoint</a> and then returns immediately back to the caller.
The message however is processed in another thread, the asynchronous thread. Then the caller
can continue doing other work and at the same time the asynchronous thread is processing the
message. This is illustrated in the diagram below:</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-em
 bedded-image" src="async.data/camel_async_request_reply.png" data-image-src="/confluence/download/attachments/117116/camel_async_request_reply.png?version=2&amp;modificationDate=1241928088000&amp;api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="10640" data-linked-resource-version="2"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_async_request_reply.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="50"></span></p><p>1.
The client sends an <a shape="rect" href="async.html">Async</a> <a shape="rect"
href="request-reply.html">Request Reply</a> message over <a shape="rect" href="http.html">HTTP</a>
to Camel. The control is immediately returned to the client application, that can continue
and do other work while Camel routes the message.<br clear="none"> 2. Camel invokes
an external <a shape="rect" href
 ="mina.html">TCP</a> service using synchronous <a shape="rect" href="request-reply.html">Request
Reply</a>. The client application can do other work simultaneously.<br clear="none">
3. The client wants to get the reply so it uses the Future handle it got as <em>response</em>
from step 1. With this handle it retrieves the reply, wait if nessasary if the reply is not
ready.</p><h3 id="Async-SynchronousRequestOnly">Synchronous Request Only</h3><p>You
can also do synchronous <a shape="rect" href="event-message.html">Request only</a>
with Camel. The client sends a message to Camel in which a reply is not expected. However
the client still waits until the message is processed completely. This is illustrated in the
diagram below:</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image" src="async.data/camel_sync_request_only.png" data-image-src="/confluence/download/attachments/117116/camel_sync_request_only.png?version=1&amp;modificationDate=124192363700
 0&amp;api=v2" data-unresolved-comment-count="0" data-linked-resource-id="10642" data-linked-resource-version="1"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_sync_request_only.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="50"></span></p><p>1.
The client sends a <a shape="rect" href="event-message.html">Request only</a>
and we can still use <a shape="rect" href="http.html">HTTP</a> despite http being
<a shape="rect" href="request-reply.html">Request Reply</a> by nature.<br clear="none">
2. Camel invokes an external <a shape="rect" href="mina.html">TCP</a> service
using synchronous <a shape="rect" href="request-reply.html">Request Reply</a>.
The client application is still waiting.<br clear="none"> 3. The message is processed
completely and the control is returned to the client.</p><p>So why do you want
to use s
 ynchronous <a shape="rect" href="event-message.html">Request Only</a>? Well if
you want to know whether the message was processed successfully or not before continuing.
With synchronous it allows you to wait while the message is being processed. In case the processing
was succesful the control is returned to the client with no notion of error. In case of failure
the client can detect this as an exception is thrown. (and <code>exchange.isFailed()</code>
returns <code>true</code>).</p><h3 id="Async-AsynchronousRequestOnly">Asynchronous
Request Only</h3><p>As opposed to the synchronous <a shape="rect" href="event-message.html">Request
Only</a> the <a shape="rect" href="async.html">Async</a> counter part will
<strong>not</strong> wait for the processing of the message to complete. In this
case the client can immediately continue doing other work while the message is being routed
and processed in Camel. This is illustrated in the diagram below:</p><p><span
class="confluence-embedded-file
 -wrapper"><img class="confluence-embedded-image" src="async.data/camel_async_request_only.png"
data-image-src="/confluence/download/attachments/117116/camel_async_request_only.png?version=1&amp;modificationDate=1241928107000&amp;api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="10644" data-linked-resource-version="1"
data-linked-resource-type="attachment" data-linked-resource-default-alias="camel_async_request_only.png"
data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png"
data-linked-resource-container-id="117116" data-linked-resource-container-version="50"></span></p><p>1.
The client sends a <a shape="rect" href="event-message.html">Request only</a>
and we can still use <a shape="rect" href="http.html">HTTP</a> despite http being
<a shape="rect" href="request-reply.html">Request Reply</a> by nature. The control
is immediately returned to the client application, that can continue and do other work while
Camel routes the m
 essage.<br clear="none"> 2. Camel invokes an external <a shape="rect" href="mina.html">TCP</a>
service using synchronous <a shape="rect" href="request-reply.html">Request Reply</a>.
The client application can do other work simultaneously.<br clear="none"> 3. The message
completes but no result is returned to the client.</p><p><strong>Notice:</strong>
As Camel always returns a <code>Future</code> handle for <a shape="rect" href="async.html">Async</a>
messaging to the client. The client can use this handler to get hold of the status of the
processing whether the task is complete or an Exception occured during processing. Note that
the client is not required to do so, its perfect valid to just ignore the Future handle.</p><div
class="confluence-information-macro confluence-information-macro-tip"><span class="aui-icon
aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>In case you want to know whether the
<a sha
 pe="rect" href="async.html">Async</a> <a shape="rect" href="event-message.html">Request
Only</a> failed, then you can use the <code>Future</code> handle and invoke
<code>get()</code> and if it throws a <code>ExecutionException</code>
then the processing failed. The caused exception is wrapped. You can invoke <code>isDone()</code>
first to test whether the task is done or still in progress. Otherwise invoking <code>get()</code>
will wait until the task is done.</p></div></div><p>With these diagrams
in mind lets turn out attention to the <a shape="rect" href="async.html">Async</a>
API and how to use it with Camel.</p><h2 id="Async-1)TheClientAPI">1) The <a
shape="rect" href="async.html">Async</a> Client API</h2><p>Camel provides
the <a shape="rect" href="async.html">Async</a> Client API in the <a shape="rect"
class="external-link" href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/ProducerTemplate.html">ProducerTemplate</a>
where we have added about 10 new
  methods to Camel 2.0. We have listed the most important in the table below:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Method</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Returns</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>setExecutorService</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>void</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Is used to set the Java ExecutorService. Camel
will by default provide a ScheduledExecutorService with 5 thread in the pool.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncSend</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Exchange&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Is used to send an async exchange
to a Camel <a shape="rect" href="endpoint.html">Endpoint</
 a>. Camel will imeddiately return control to the caller thread after the task has been
submitted to the executor service. This allows you to do other work while Camel processes
the exchange in the other async thread.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>asyncSendBody</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>As above but for sending body only.
This is a request only messaging style so no reply is expected. Uses the <code>InOnly</code>
exchange pattern.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>asyncRequestBody</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>As above but for sending body only. This is a
<a shape="rect" href="request-reply.html">Request Reply</a> messaging style so
a reply is expected. Uses the <code>InOut</code> exchange
  pattern.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>extractFutureBody</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>T</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Is used to get the result from the asynchronous
thread using the Java Concurrency Future handle.</p></td></tr></tbody></table></div><p>The
<code>asyncSend</code> and <code>asyncRequest</code> methods return
a Future handle. This handle is what the caller must use later to retrieve the asynchronous
response. You can do this by using the <code>extractFutureBody</code> method,
or just use plain Java but invoke <code>get()</code> on the <code>Future</code>
handle.</p><h3 id="Async-TheClientAPIwithcallbacks">The <a shape="rect" href="async.html">Async</a>
Client API with callbacks</h3><p>In addition to the Client API from above Camel
provides a variation that uses <a shape="rect" href="oncompletion.html">callbacks</a>
when the message <a shape="rect" href="exchange.html">E
 xchange</a> is done.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th
colspan="1" rowspan="1" class="confluenceTh"><p>Method</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Returns</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncCallback</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Exchange&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>In addition a callback is passed
in as a parameter using the <code>org.apache.camel.spi.Synchronization</code>
Callback. The callback is invoked when the message exchange is done.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncCallbackSendBody</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>As above but for sending body only.
This is a request only messaging s
 tyle so no reply is expected. Uses the <code>InOnly</code> exchange pattern.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asyncCallbackRequestBody</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Future&lt;Object&gt;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>As above but for sending body only.
This is a <a shape="rect" href="request-reply.html">Request Reply</a> messaging
style so a reply is expected. Uses the <code>InOut</code> exchange pattern.</p></td></tr></tbody></table></div><p>These
methods also returns the Future handle in case you need them. The difference is that they
invokes the callback as well when the <a shape="rect" href="exchange.html">Exchange</a>
is done being routed.</p><h4 id="Async-TheFutureAPI">The Future API</h4><p>The
<code>java.util.concurrent.Future</code> API have among others the following methods:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="co
 nfluenceTh"><p>Method</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Returns</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>isDone</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>boolean</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Returns a boolean whether the task
is done or not. Will even return <code>true</code> if the tasks failed due to
an exception thrown.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>get()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Object</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Gets the response of the task. In case of an exception was
thrown the <code>java.util.concurrent.ExecutionException</code> is thrown with
the caused exception.</p></td></tr></tbody></table></div><h3
id="Async-Example:AsynchronousRequestReply">Example: Asynchronous Request Reply</h3><p>Suppose
w
 e want to call a <a shape="rect" href="http.html">HTTP</a> service but it is
usually slow and thus we do not want to block and wait for the response, as we can do other
important computation. So we can initiate an <a shape="rect" href="async.html">Async</a>
exchange to the <a shape="rect" href="http.html">HTTP</a> endpoint and then do
other stuff while the slow <a shape="rect" href="http.html">HTTP</a> service is
processing our request. And then a bit later we can use the <code>Future</code>
handle to get the response from the <a shape="rect" href="http.html">HTTP</a>
service. Yeah nice so lets do it:</p><p>First we define some routes in Camel.
One for the <a shape="rect" href="http.html">HTTP</a> service where we simulate
a slow server as it takes at least 1 second to reply. And then other route that we want to
invoke while the <a shape="rect" href="http.html">HTTP</a> service is on route.
This allows you to be able to process the two routes simultaneously:</p><div class="code
pane
 l pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[
 // The mocks are here for unit test
 




Mime
View raw message