This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new b5a5dc2 Polish and cleanup documentation
b5a5dc2 is described below
commit b5a5dc2081591c43e0d77c11ffa790fc77eb6417
Author: Claus Ibsen <[email protected]>
AuthorDate: Fri Aug 20 10:40:29 2021 +0200
Polish and cleanup documentation
---
.../assets/images/camel_async_request_only.png | Bin 59864 -> 0 bytes
.../assets/images/camel_async_request_reply.png | Bin 64513 -> 0 bytes
.../ROOT/assets/images/camel_sync_request_only.png | Bin 59351 -> 0 bytes
.../assets/images/camel_sync_request_reply.png | Bin 61299 -> 0 bytes
docs/user-manual/modules/ROOT/nav.adoc | 1 -
docs/user-manual/modules/ROOT/pages/async.adoc | 440 ---------------------
docs/user-manual/modules/ROOT/pages/index.adoc | 1 -
7 files changed, 442 deletions(-)
diff --git
a/docs/user-manual/modules/ROOT/assets/images/camel_async_request_only.png
b/docs/user-manual/modules/ROOT/assets/images/camel_async_request_only.png
deleted file mode 100644
index 088bcc0..0000000
Binary files
a/docs/user-manual/modules/ROOT/assets/images/camel_async_request_only.png and
/dev/null differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/camel_async_request_reply.png
b/docs/user-manual/modules/ROOT/assets/images/camel_async_request_reply.png
deleted file mode 100644
index 950e87e..0000000
Binary files
a/docs/user-manual/modules/ROOT/assets/images/camel_async_request_reply.png and
/dev/null differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/camel_sync_request_only.png
b/docs/user-manual/modules/ROOT/assets/images/camel_sync_request_only.png
deleted file mode 100644
index 777d86a..0000000
Binary files
a/docs/user-manual/modules/ROOT/assets/images/camel_sync_request_only.png and
/dev/null differ
diff --git
a/docs/user-manual/modules/ROOT/assets/images/camel_sync_request_reply.png
b/docs/user-manual/modules/ROOT/assets/images/camel_sync_request_reply.png
deleted file mode 100644
index e0ed424..0000000
Binary files
a/docs/user-manual/modules/ROOT/assets/images/camel_sync_request_reply.png and
/dev/null differ
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index 94c0de1..df5c190 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -26,7 +26,6 @@
** xref:camel-3-migration-guide.adoc[Camel 2.x to 3.0 Migration Guide]
** xref:camel-3x-upgrade-guide.adoc[Camel 3.x Upgrade Guide]
* xref:architecture.adoc[Architecture]
-** xref:async.adoc[Async]
** xref:backlogdebugger.adoc[Backlog debugger]
** xref:backlog-tracer.adoc[Backlog Tracer]
** xref:batch-consumer.adoc[Batch Consumer]
diff --git a/docs/user-manual/modules/ROOT/pages/async.adoc
b/docs/user-manual/modules/ROOT/pages/async.adoc
deleted file mode 100644
index 9e371e8..0000000
--- a/docs/user-manual/modules/ROOT/pages/async.adoc
+++ /dev/null
@@ -1,440 +0,0 @@
-[[Async-Async]]
-= Async
-
-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.
-
-== 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.
-
-== 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
-
-=== 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.
-
-=== 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.
-
-== 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:{eip-vc}:eips: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`).
-
-== 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.
-
-*Notice:* As Camel always returns a `Future` handle for
-Async 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 occurred during processing. Note that the client
-is not required to do so, it's perfectly valid to just ignore the Future
-handle.
-
-TIP: In case you want to know whether the Async
-Request Only failed, then you can use the
-`Future` handle and invoke `get()` and if it throws a
-`ExecutionException` then the processing failed. The caused exception is
-wrapped. You can invoke `isDone()` first to test whether the task is
-done or still in progress. Otherwise invoking `get()` will wait until
-the task is done.
-
-With these diagrams in mind, lets turn out attention to the
-Async API and how to use it with Camel.
-
-== The Async Client API
-
-Camel provides the Async Client API in the
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/ProducerTemplate.html[ProducerTemplate]
-where we have added about 10 new methods to Camel 2.0. We have listed
-the most important in the table below:
-
-[width="100%",cols="10%,10%,80%",options="header",]
-|=======================================================================
-|Method |Returns |Description
-
-|setExecutorService |void |Is used to set the Java ExecutorService. Camel will
by default provide a
-ScheduledExecutorService with 5 thread in the pool.
-
-|asyncSend |Future<Exchange> |Is used to send an async exchange to a Camel
-Endpoint. Camel will immediately 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 |Future<Object> |As above but for sending body only. This is a
request only messaging
-style so no reply is expected. Uses the `InOnly` exchange pattern.
-
-|asyncRequestBody |Future<Object> |As above but for sending body only. This is
a
-Request Reply messaging style so a reply is
-expected. Uses the `InOut` exchange pattern.
-
-|extractFutureBody |T |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.
-
-== The Async Client API with callbacks
-
-In addition to the Client API from above Camel provides a variation that
-uses callbacks when the message
-Exchange is done.
-
-[width="100%",cols="10%,10%,80%",options="header",]
-|=======================================================================
-|Method |Returns |Description
-
-|asyncCallback |Future<Exchange> |In addition, a callback is passed in as a
parameter using the
-`org.apache.camel.spi.Synchronization` Callback. The callback is invoked
-when the message exchange is done.
-
-|asyncCallbackSendBody |Future<Object> |As above but for sending body only.
This is a request only messaging
-style so no reply is expected. Uses the `InOnly` exchange pattern.
-
-|asyncCallbackRequestBody |Future<Object> |As above but for sending body only.
This is a
-Request Reply messaging style so a reply is
-expected. Uses the `InOut` exchange pattern.
-|=======================================================================
-
-These methods also returns the Future handle in case you need them. The
-difference is that they invokes the callback as well when the
-Exchange is done being routed.
-
-=== The Future API
-
-The `java.util.concurrent.Future` API have among others the following
-methods:
-
-[width="100%",cols="10%,10%,80%",options="header",]
-|=======================================================================
-|Method |Returns |Description
-
-|isDone |boolean |Returns a boolean whether the task is done or not. Will even
return
-`true` if the tasks failed due to an exception thrown.
-
-|get() |Object |Gets the response of the task. In case of an exception was
thrown the
-`java.util.concurrent.ExecutionException` is thrown with the caused
-exception.
-|=======================================================================
-
-== Example: Asynchronous Request Reply
-
-Suppose we want to call an xref:components::http-component.adoc[HTTP] 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
-Async exchange to the HTTP endpoint and
-then do other stuff while the slow xref:components::http-component.adoc[HTTP]
service is
-processing our request. And then a bit later we can use the `Future`
-handle to get the response from the xref:components::http-component.adoc[HTTP]
service. Yeah
-nice so let's do it:
-
-First, we define some routes in Camel. One for the
xref:components::http-component.adoc[HTTP]
-service where we simulate a slow server as it takes at least 1 second to
-reply. And then another route that we want to invoke while the
-xref:components::http-component.adoc[HTTP] service is on route. This allows
you to be able to
-process the two routes simultaneously:
-
-[source,java]
----------------------------------------------------------------------------
-// Some other service to return a name, this is invoked synchronously
-from("direct:name")
- .transform(constant("Claus"))
- .to("mock:result");
-
-// Simulate a slow http service (delaying 1 sec) we want to invoke async
-from("jetty:http://0.0.0.0:%s/myservice";, getPort())
- .delay(1000)
- .transform(constant("Bye World"))
- .to("mock:result");
----------------------------------------------------------------------------
-
-And then we have the client API where we call the two routes and we can
-get the responses from both of them. As the code is based on a unit test
-there is a bit of mock in there as well:
-
-[source,java]
----------------------------------------------------------------------------
-MockEndpoint mock = getMockEndpoint("mock:result");
-// We expect the name job to be faster than the async job even though the
async job
-// was started first
-mock.expectedBodiesReceived("Claus", "Bye World");
-
-// Send a async request/reply message to the http endpoint
-Future<Object> future = template.asyncRequestBody("http://0.0.0.0:"; +
getPort() + "/myservice", "Hello World");
-
-// We got the future so in the meantime we can do other stuff, as this is Camel
-// so lets invoke another request/reply route but this time is synchronous
-String name = template.requestBody("direct:name", "Give me a name",
String.class);
-assertEquals("Claus", name);
-
-// Okay we got a name and we have done some other work at the same time
-// the async route is running, but now its about time to wait and get
-// get the response from the async task
-
-// We use the extract future body to get the response from the future
-// (waiting if needed) and then return a string body response.
-// This allows us to do this in a single code line instead of using the
-// JDK Future API to get hold of it, but you can also use that if you want
-// Adding the (String) To make the CS happy
-String response = template.extractFutureBody(future, String.class);
-assertEquals("Bye World", response);
-
-assertMockEndpointsSatisfied();
----------------------------------------------------------------------------
-
-All together it should give you the basic idea of how to use this
-Async API and what it can do.
-
-== Example: Synchronous Request Reply
-
-This example is just a pure synchronous version of the async based example
above.
-
-The route is the same, so its just how the client initiate and send the
-messages that differs:
-
-[source,java]
----------------------------------------------------------------------------
-MockEndpoint mock = getMockEndpoint("mock:result");
-// We expect the http job to complete before the name job
-mock.expectedBodiesReceived("Bye World", "Claus");
-
-// Send a sync request/reply message to the http endpoint
-String response = template.requestBody("http://0.0.0.0:"; + getPort() +
"/myservice", "Hello World", String.class);
-assertEquals("Bye World", response);
-
-// Send a sync request/reply message to the direct endpoint
-String name = template.requestBody("direct:name", "Give me a name",
String.class);
-assertEquals("Claus", name);
-
-assertMockEndpointsSatisfied();
----------------------------------------------------------------------------
-
-== Using the Async API with callbacks
-
-Suppose we want to call an xref:components::http-component.adoc[HTTP] service
but it is usually
-slow and thus we do not want to block and wait for the response, but
-instead let a callback gather the response. This allows us to send
-multiple requests without waiting for the replies before we can send the
-next request.
-
-First, we define a route in Camel for the
xref:components::http-component.adoc[HTTP] service
-where we simulate a slow server as it takes at least 1 second to reply.
-
-[source,java]
----------------------------------------------------------------------------
-// The mocks are here for unit test
-// Simulate a slow http service (delaying a bit) we want to invoke async
-from("jetty:http://0.0.0.0:"; + getPort() + "/myservice")
- .delay(300)
- .transform(body().prepend("Hello "))
- .to("mock:result");
----------------------------------------------------------------------------
-
-Then we define our callback where we gather the responses. As this is
-based on a unit test it just gathers the responses in a list. This is a
-shared callback we use for every request we send in, but you can use
-your own individual or use an anonymous callback. The callback supports
-different methods, but we use `onDone` that is invoked regardless if the
-Exchange was processed successfully or failed. The
-`org.apache.camel.spi.Synchronization` API provides fine-grained methods
-for `onCompletion` and `onFailure` for the two situations.
-
-[source,java]
----------------------------------------------------------------------------
-/**
- * Our own callback that will gather all the responses.
- * We extend the SynchronizationAdapter class as we then only need to override
the onComplete method.
- */
-private static class MyCallback extends SynchronizationAdapter {
-
- // below the String elements are added in the context of different threads
so that we should make
- // sure that this's done in a thread-safe manner, that's no two threads
should call the data.add()
- // method below concurrently, so why we use Vector here and not e.g.
ArrayList
- private final List<String> data = new Vector<>();
-
- @Override
- public void onComplete(Exchange exchange) {
- // this method is invoked when the exchange was a success and we can get
the response
- String body = exchange.getOut().getBody(String.class);
- data.add(body);
-
- // the latch is used for testing purposes
- LATCH.countDown();
- }
-
- public List<String> getData() {
- return data;
- }
-}
----------------------------------------------------------------------------
-
-And then we have the client API where we call the
xref:components::http-component.adoc[HTTP]
-service using `asyncCallback` 3 times with different input. As the
-invocation is Async the client will send 3 requests
-right after each other, so we have 3 concurrent exchanges in progress.
-The response is gathered by our callback so we do not have to care how
-to get the response.
-
-
-[source,java]
----------------------------------------------------------------------------
-MyCallback callback = new MyCallback();
-
-// Send 3 async request/reply message to the http endpoint
-// where we let the callback handle gathering the responses
-String url = "http://localhost:"; + getPort() + "/myservice";
-template.asyncCallbackRequestBody(url, "Claus", callback);
-template.asyncCallbackRequestBody(url, "Hadrian", callback);
-template.asyncCallbackRequestBody(url, "Willem", callback);
----------------------------------------------------------------------------
-
-== Using the Async API with the Camel classic API
-
-When using the Camel API to create a producer and send an
-Exchange we do it like this:
-
-[source,java]
----------------------------------------------------------------------------
-Endpoint endpoint = context.getEndpoint("http://slowserver.org/myservice";);
-Exchange exchange = endpoint.createExchange();
-exchange.getIn().setBody("Order ABC");
-// create a regular producer
-Producer producer = endpoint.createProducer();
-// send the exchange and wait for the reply as this is synchronous
-producer.process(exchange);
----------------------------------------------------------------------------
-
-But to do the same with Async we need a little help
-from a helper class, so the code is:
-
-[source,java]
-------------------------------------------------------------------------------------------------------------------------------
-Endpoint endpoint = context.getEndpoint("http://slowserver.org/myservice";);
-Exchange exchange = endpoint.createExchange();
-exchange.getIn().setBody("Order ABC");
-// create a regular producer
-Producer producer = endpoint.createProducer();
-// normally you will use a shared executor service with pools
-ExecutorService executor = Executors.newSingleThreadExecutor();
-// send it async with the help of this helper
-Future<Exchange> future = AsyncProcessorHelper.asyncProcess(executor,
producer, exchange);
-// here we got the future handle and we can do other stuff while the exchange
is being routed in the other asynchronous thread
-...
-// and to get the response we use regular Java Concurrency API
-Exchange response = future.get();
-------------------------------------------------------------------------------------------------------------------------------
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc
b/docs/user-manual/modules/ROOT/pages/index.adoc
index 22088e90..a52e77e 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -64,7 +64,6 @@ For a deeper and better understanding of Apache Camel, an
xref:faq:what-is-camel
=== xref:architecture.adoc[Architecture]
-* xref:async.adoc[Async]
* xref:backlogdebugger.adoc[BacklogDebugger]
* xref:backlog-tracer.adoc[BacklogTracer]
* xref:batch-consumer.adoc[Batch Consumer]
