<commit_before>[[Async-Async]]
= Async

*Since Camel 2.0*

The asynchronous API in Camel has been rewritten for Camel 2.0, and the
information on this page applies for Camel 2.0 and later.

The Async API in Camel is primarily divided in two
areas +
 1. Initiating an Async messaging from the client +
 2. Turning a route into Async using the *threads*
DSL

Before we look at these two areas we start with a bit of background
information and look at the concept from a higher level using
diagrams. +
 Then we check out the first area how a client can initiate an
Async message exchange and we also throw in the
synchronous message exchange in the mix as well so we can compare and
distill the difference. +
 And finally, we turn our attention towards the last area the new
*threads* DSL and what it can be used for.

[[Async-Background]]
== Background

The new Async API in Camel 2.0 leverages in much
greater detail the Java Concurrency API and its support for executing
tasks asynchronously. +
 Therefore the Camel Async API should be familiar for
users with knowledge of the Java Concurrency API.

[[Async-Afewconceptstomaster]]
== 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 known as fire and forget or
event message.

The Request Reply is when the caller sends a
message and then *waits for a reply*. This is like the
xref:components::http-component.adoc[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 `InOnly` for the request only and `InOut` for the
request reply.

For all message exchange they can be executed either:

* synchronous
* asynchronous

[[Async-SynchronousRequestReply]]
=== Synchronous Request Reply

A synchronous exchange is defined as the caller sends a message and
waits until it's complete before continuing. This is illustrated in the
diagram below:

image::camel_sync_request_reply.png[image]

\1. The client sends a sync Request Reply
message over xref:components::http-component.adoc[HTTP] to Camel. The client application will
wait for the response that Camel routes and processes. +
 2. The message invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application still waits for the response. +
 3. The response is sent back to the client.

[[Async-AsynchronousRequestReply]]
=== Asynchronous Request Reply

On the other hand, the asynchronous version is where the caller sends a
message to an Endpoint 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:

image::camel_async_request_reply.png[image]

 1. The client sends an Async
Request Reply message over HTTP
to Camel. The control is immediately returned to the client application,
that can continue and do other work while Camel routes the message. +
 2. Camel invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application can do other work simultaneously. +
 3. The client wants to get the reply so it uses the Future handle it
got as _response_ from step 1. With this handle it retrieves the reply,
wait if necessary if the reply is not ready.

[[Async-SynchronousRequestOnly]]
== Synchronous Request Only

You can also do synchronous Request only 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:

image::camel_sync_request_only.png[image]

\1. The client sends a Request only and we can
still use xref:components::http-component.adoc[HTTP] despite http being
Request Reply by nature. +
 2. Camel invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application is still waiting. +
 3. The message is processed completely and the control is returned to
the client.

So why do you want to use synchronous xref:event-message.adoc[Request Only]? 
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
successful 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 `exchange.isFailed()` returns `true`).

[[Async-AsynchronousRequestOnly]]
== Asynchronous Request Only

As opposed to the synchronous Request Only the
Async counterpart will *not* 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:

image::camel_async_request_only.png[image]

\1. The client sends a Request only and we can
still use xref:components::http-component.adoc[HTTP] despite http being
Request Reply by nature. The control is
immediately returned to the client application, that can continue and do
other work while Camel routes the message. +
 2. Camel invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application can do other work simultaneously. +
 3. The message completes but no result is returned to the client.
<commit_msg>doc: fix numbered list in async documentation<commit_after>[[Async-Async]]
= Async

*Since Camel 2.0*

The asynchronous API in Camel has been rewritten for Camel 2.0, and the
information on this page applies for Camel 2.0 and later.

The Async API in Camel is primarily divided in two
areas +
 1. Initiating an Async messaging from the client +
 2. Turning a route into Async using the *threads*
DSL

Before we look at these two areas we start with a bit of background
information and look at the concept from a higher level using
diagrams. +
 Then we check out the first area how a client can initiate an
Async message exchange and we also throw in the
synchronous message exchange in the mix as well so we can compare and
distill the difference. +
 And finally, we turn our attention towards the last area the new
*threads* DSL and what it can be used for.

[[Async-Background]]
== Background

The new Async API in Camel 2.0 leverages in much
greater detail the Java Concurrency API and its support for executing
tasks asynchronously. +
 Therefore the Camel Async API should be familiar for
users with knowledge of the Java Concurrency API.

[[Async-Afewconceptstomaster]]
== 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 known as fire and forget or
event message.

The Request Reply is when the caller sends a
message and then *waits for a reply*. This is like the
xref:components::http-component.adoc[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 `InOnly` for the request only and `InOut` for the
request reply.

For all message exchange they can be executed either:

* synchronous
* asynchronous

[[Async-SynchronousRequestReply]]
=== Synchronous Request Reply

A synchronous exchange is defined as the caller sends a message and
waits until it's complete before continuing. This is illustrated in the
diagram below:

image::camel_sync_request_reply.png[image]

 1. The client sends a sync Request Reply
message over xref:components::http-component.adoc[HTTP] to Camel. The client application will
wait for the response that Camel routes and processes. +
 2. The message invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application still waits for the response. +
 3. The response is sent back to the client.

[[Async-AsynchronousRequestReply]]
=== Asynchronous Request Reply

On the other hand, the asynchronous version is where the caller sends a
message to an Endpoint 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:

image::camel_async_request_reply.png[image]

 1. The client sends an Async
Request Reply message over HTTP
to Camel. The control is immediately returned to the client application,
that can continue and do other work while Camel routes the message. +
 2. Camel invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application can do other work simultaneously. +
 3. The client wants to get the reply so it uses the Future handle it
got as _response_ from step 1. With this handle it retrieves the reply,
wait if necessary if the reply is not ready.

[[Async-SynchronousRequestOnly]]
== Synchronous Request Only

You can also do synchronous Request only 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:

image::camel_sync_request_only.png[image]

 1. The client sends a Request only and we can
still use xref:components::http-component.adoc[HTTP] despite http being
Request Reply by nature. +
 2. Camel invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application is still waiting. +
 3. The message is processed completely and the control is returned to
the client.

So why do you want to use synchronous xref:event-message.adoc[Request Only]? 
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
successful 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 `exchange.isFailed()` returns `true`).

[[Async-AsynchronousRequestOnly]]
== Asynchronous Request Only

As opposed to the synchronous Request Only the
Async counterpart will *not* 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:

image::camel_async_request_only.png[image]

 1. The client sends a Request only and we can
still use xref:components::http-component.adoc[HTTP] despite http being
Request Reply by nature. The control is
immediately returned to the client application, that can continue and do
other work while Camel routes the message. +
 2. Camel invokes an external xref:components::mina-component.adoc[TCP] service using
synchronous Request Reply. The client
application can do other work simultaneously. +
 3. The message completes but no result is returned to the client.

{'fraction_non_alphanumeric': 0.04471339720961506, 'fraction_numerical': 0.0038661959993276183, 'mean_word_length': 4.615384615384615, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1879181', 'n_tokens_mistral': 3095, 'n_tokens_neox': 2925, 'n_words': 1778}