THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Async
Available as of Camel 2.0
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.
A bit of background
The new Async API in Camel 2.0 leverages in much greater detail the Java Concurrency API and its support for executing tasks asynchronous.
Therefore the Camel Async API should be familiar for users with knowledge of the Java Concurrency API.
A few concepts to master
When doing messaging there are a few aspects to keep in mind.
First of all a caller can initiate a message exchange as either:
- request only
- request reply
Request only is when the caller sends a message but do not expect any reply. This is also sometimes known as fire and forget or event message.
The Request Reply is then caller sends a message and then waits for a reply. This is like the Http protocol that we use every day when we surf the web.
We send a request to fetch a web page and wait until the reply message comes with the web content.
In Camel a message is labeled with a Message Exchange Pattern that labels whether its a request only or request reply message. Camel uses the JBI term for this an uses InOnly for the request only, and InOut for the request reply.
For both the request only and the request reply the routing in Camel can happen either:
- synchronous
- asynchronous.
A sync is defined as the caller thread and the remaining routing and processing of the message is happening in the same thread and as sync the caller waits until this thread has done its work before the invocation can return to the caller and continue its work. This is illustrated in the diagram below:
TODO: picture
On the other hand the asynchronous version is where the caller thread initiates the request and leave the further processing of the message in another thread, the asynchronous thread, and then immediately returns to the caller. Then the caller can continue doing other work and at the same time the asynchronous thread is processing the message. If we are using [Request Reply then at a later point in time the original caller can get hold of the response from the asynchronous thread. If we are using request only then there are no response but the caller can still get a kind of response as it can get information whether the asynchronous thread is done or failed due to an exception. This is illustrated in the diagram below:
In the following we will look at how to use this new Async API in Camel.
The Async API
Camel provides the Async API in the Producer Template where we have added about 10 new methods to Camel 2.0. We have listed the most important in the table below:
Method |
Description |
|---|---|
setExecutorService |
Is used to set the Java ExecutorService. Camel will by default provide a ScheduledExecutorService with 5 thread in the pool. |
asyncSend |
Is used to send an async exchange to a Camel Endpoint. 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. |
asyncSendBody |
As above but for sending body only. This is a request only messaging style so no reply is expected. Uses the |
asyncRequestBody |
As above but for sending body only. This is a Request Reply messaging style so a reply is expected. Uses the |
extractFutureBody |
Is used to get the result from the asynchronous thread using the Java Concurrency Future handle. |
The asyncSend and asyncRequest 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 extractFutureBody method, or just use plain Java but invoke get() on the Future handle.