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
commit 98250f71699216b26c05ef16df6c5774bec14b4e
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Wed Aug 11 14:06:19 2021 +0200
Polish and cleanup documentation
---
.../modules/ROOT/pages/oncompletion.adoc | 76 +++++++++-------------
1 file changed, 30 insertions(+), 46 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
index 3eb8523..13f140e 100644
--- a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
+++ b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
@@ -1,27 +1,25 @@
[[OnCompletion-OnCompletion]]
= OnCompletion
-Camel has this concept of a Unit of Work that encompass the
+Camel has this concept of a _Unit of Work_ that encompass the
Exchange. The unit of work among others supports
synchronization callbacks that are invoked when the
Exchange is complete. The callback API is defined in
-`org.apache.camel.spi.Synchronization`. and the extended synchronization
+`org.apache.camel.spi.Synchronization` and the extended synchronization
`org.apache.camel.spi.SynchronizationRouteAware` that have callbacks for
route events.
-*Getting the UnitOfWork*
+== UnitOfWork API
You can get hold of the `org.apache.camel.spi.UnitOfWork` from
`org.apache.camel.Exchange` with the method `getUnitOfWork()`.
-*OnCompletion DSL*
+== OnCompletion DSL
-The *onCompletion* EIP supports the following features:
+The OnCompletion EIP supports the following features:
-* scope: global and/or per route (route scope override all global scope)
-* multiple global scope
-* triggered either always, only if completed with success, or only if
-failed
+* level: context or route (route level override global level)
+* triggered either always, only if completed with success, or only if failed
* `onWhen` predicate to only trigger if matched
* `mode` to define whether to run either before or after
route consumer writes response back to callee (if its InOut) (default
AfterConsumer)
@@ -35,22 +33,21 @@ allows to modify the exchange before the consumer writes
back any
response to the callee. You can use this to for example add customer
headers, or send to a log to log the response message, etc.
-[[OnCompletion-onCompletionwithroutescope]]
-== onCompletion with route scope
+=== onCompletion with route scope
-The *onCompletion* DSL allows you to add custom routes/processors when
+The OnCompletion EIP allows you to add custom routes/processors when
the original Exchange is complete. Camel spins off a
copy of the Exchange and routes it in a separate
thread, similar to a Wire Tap. This allows the
-original thread to continue while the *onCompletion* route is running
+original thread to continue while the onCompletion route is running
concurrently. We chose this model as we did not want the
-*onCompletion* route to interfere with the original route.
+onCompletion route to interfere with the original route.
-*Multiple onCompletions allowed at both route and global scope*
+=== Multiple onCompletions
-You may define multiple onCompletions at both context and route scope.
-When you define route scoped
-onCompletions then any context scoped are disabled for that given route.
+You may define multiple onCompletions at both context and route level.
+
+When you define route level onCompletions then any context levels are disabled
for that given route.
[source,java]
-----------------------------------------------------------
@@ -67,7 +64,7 @@ from("direct:start")
.to("mock:result");
-----------------------------------------------------------
-By default the *onCompletion* will be triggered when the
+By default the OnCompletion EIP will be triggered when the
Exchange is complete and regardless if the
Exchange completed with success or with a failure
(such as an Exception was thrown). You can limit the trigger to only
@@ -92,11 +89,9 @@ from("direct:start")
-----------------------------------------------------------
You can identify if the Exchange is an
-*onCompletion* Exchange as Camel will add the
-property `Exchange.ON_COMPLETION` with a boolean value of `true` when it
-spin-off the *onCompletion* Exchange.
+OnCompletion Exchange as Camel will add the
+property `Exchange.ON_COMPLETION` with a boolean value of `true`.
-[[OnCompletion-UsingonCompletionfromSpringDSL]]
=== Using onCompletion from XML DSL
The onCompletion is defined like this with XML DSL:
@@ -118,7 +113,7 @@ The onCompletion is defined like this with XML DSL:
----
And the `onCompleteOnly` and `onFailureOnly` is defined as a boolean
-attribute on the <onCompletion> tag so the failure example would be:
+attribute on the `<onCompletion>` tag, so the failure example would be:
[source,xml]
----
@@ -135,10 +130,9 @@ attribute on the <onCompletion> tag so the failure example
would be:
</route>
----
-[[OnCompletion-onCompletionwithglobalscope]]
-== onCompletion with global scope
+=== onCompletion with global level
-This works just like the route scope except from the fact that they are
+This works just like the route level except from the fact that they are
defined globally. An example below:
[source,java]
@@ -151,11 +145,7 @@ from("direct:start")
.to("mock:result");
----
-[[OnCompletion-UsingonCompletionfromSpringDSL.1]]
-=== Using onCompletion from Spring DSL
-
-This works just like the route scope except from the fact that they are
-defined globally. An example below:
+And in XML:
[source,xml]
----
@@ -173,19 +163,16 @@ defined globally. An example below:
</route>
----
-
-*Route scope override Global scope*
-If an *onCompletion* is defined in a route, it overrides *all* global
+IMPORTANT: If an OnCompletion is defined in a route, it overrides *all* global
scoped and thus it is only the route scoped that are used. The globally
scoped are not in use.
-[[OnCompletion-UsingonCompletionwithonWhenpredicate]]
-== Using onCompletion with onWhen predicate
+=== Using onCompletion with onWhen predicate
As other DSL in Camel you can attach a predicate to
-the *onCompletion* so it only triggers in certain conditions, when the
+the OnCompletion so it only triggers in certain conditions, when the
predicate matches. For example to only trigger if the message body contains
the word
-`Hello` we can do like:
+_Hello_ we can do like:
[source,java]
----
@@ -202,7 +189,6 @@ from("direct:start")
.to("mock:result");
----
-[[OnCompletion-UsingonCompletionwithorwithoutthreadpool]]
== Using onCompletion with or without thread pool
To use thread pool then either set a `executorService` or set
@@ -218,7 +204,7 @@ onCompletion().parallelProcessing()
.setBody(simple("OnComplete:${body}"));
----
-And in XML DSL
+And in XML DSL:
[source,xml]
----
@@ -230,7 +216,7 @@ And in XML DSL
----
You can also refer to a specific thread pool
-to be used, using the executorServiceRef option
+to be used, using the `executorServiceRef` option
[source,xml]
----
@@ -241,11 +227,9 @@ to be used, using the executorServiceRef option
</onCompletion>
----
+=== OnCompletion consumer modes
-[[OnCompletion-UsingonCompletiontorunbeforerouteconsumersendsbackresponsetocallee]]
-== Using onCompletion to run before route consumer sends back response to
callee
-
-OnCompletion supports two modes
+OnCompletion supports two modes that affects the route consumer:
* AfterConsumer - Default mode which runs after the consumer is done
* BeforeConsumer - Runs before the consumer is done, and before the
