Added onCompletion docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/bd6f1d28 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/bd6f1d28 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/bd6f1d28 Branch: refs/heads/master Commit: bd6f1d284a25015bc7a9a4aa69e0cdbcda38d923 Parents: 72a6ab4 Author: Andrea Cosentino <[email protected]> Authored: Sun Jul 31 11:56:16 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Sun Jul 31 11:56:16 2016 +0200 ---------------------------------------------------------------------- docs/user-manual/en/SUMMARY.md | 2 +- docs/user-manual/en/oncompletion.adoc | 332 +++++++++++++++++++++++++++++ 2 files changed, 333 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/bd6f1d28/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 842c71a..d3111e4 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -38,12 +38,12 @@ * [Intercept](intercept.adoc) * [Inversion Of Control With Smart Defaults](inversion-of-control-with-smart-defaults.adoc) * [Lifecycle](lifecycle.adoc) + * [OnCompletion](oncompletion.adoc) * [Registry](registry.adoc) * [RX](rx.adoc) * [Scala DSL](scala-dsl.adoc) <!-- - * [OnCompletion](.adoc) * [Pluggable Class Resolvers](.adoc) * [Predicate](.adoc) * [Processor](.adoc) http://git-wip-us.apache.org/repos/asf/camel/blob/bd6f1d28/docs/user-manual/en/oncompletion.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/oncompletion.adoc b/docs/user-manual/en/oncompletion.adoc new file mode 100644 index 0000000..e9c117e --- /dev/null +++ b/docs/user-manual/en/oncompletion.adoc @@ -0,0 +1,332 @@ +[[OnCompletion-OnCompletion]] +OnCompletion +~~~~~~~~~~~~ + +Camel has this concept of a Unit of Work that encompass the +link:exchange.html[Exchange]. The unit of work among others supports +synchronization callbacks that are invoked when the +link:exchange.html[Exchange] is complete. The callback API is defined in +`org.apache.camel.spi.Synchronization`. From *Camel 2.14* onwards we +have an extended synchronization +`org.apache.camel.spi.SynchronizationRouteAware` that have callbacks for +route events. + +*Getting the UnitOfWork* + +You can get hold of the `org.apache.camel.spi.UnitOfWork` from +`org.apache.camel.Exchange` with the method `getUnitOfWork()`. + +In Camel 2.0 we have added DSL for these callbacks using the new +*onCompletion* DSL name. + +*onCompletion* 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 +* `onWhen` predicate to only trigger in certain situations +* *Camel 2.14:* mode: to define whether to run either before or after +route consumer writes response back to callee (if its InOut) +* *Camel 2.14:*whether to run async or sync (use a thread pool or not) + +From *Camel 2.14* onwards the onCompletion has been modified to support +running the completion task in either synchronous or asynchronous mode +(using a thread pool) and also whether to run before or after the route +consumer is done. The reason is to give more flexibility. For example to +specify to run synchronous and before the route consumer is done, which +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. + + +*Changes from Camel 2.14 onwards* +The onCompletion has changed defaults and behavior from Camel 2.14 +onwards. It now runs +* Runs synchronously without any thread pool +In Camel 2.13 the defaults were +* Runs asynchronous using a thread pool + + +*Camel 2.13 or older - On completion runs in separate thread* + +The *onCompletion* runs in a separate thread in parallel with the +original route. It is therefore not intended to influence the outcome of +the original route. The idea for on completion is to spin off a new +thread to eg send logs to a central log database, send an email, send +alterts to a monitoring system, store a copy of the result message +etc. + + Therefore if you want to do some work that influence the original +route, then do *not* use *onCompletion* for that. Notice: if you use the +`UnitOfWork` API as mentioned in the top of this page, then you can +register a `Synchronization` callback on the +link:exchange.html[Exchange] which is executed in the original route. +That way allows you to do some custom code when the route is completed; +this is how custom components can enlist on completion services which +they need, eg the link:file2.html[File] component does that for work +that moves/deletes the original file etc. + +[[OnCompletion-onCompletionwithroutescope]] +onCompletion with route scope +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The *onCompletion* DSL allows you to add custom routes/processors when +the original link:exchange.html[Exchange] is complete. Camel spin off a +copy of the link:exchange.html[Exchange] and routes it in a separate +thread, kinda like a link:wire-tap.html[Wire Tap]. This allows the +original thread to continue while the *onCompletion* route is running +concurrently. We decided for this model as we did not want the +*onCompletion* route to interfere with the original route. + +*Only 1 onCompletion supported by route scope* + +You can only have 1 onCompletion in a route. Only at context scoped +level you can have multiple. And notice that when you use a route scoped +onCompletion then any context scoped are disabled for that given route. + +[source,java] +----------------------------------------------------------- +from("direct:start") + .onCompletion() + // this route is only invoked when the original route is complete as a kind + // of completion callback + .to("log:sync") + .to("mock:sync") + // must use end to denote the end of the onCompletion route + .end() + // here the original route contiues + .process(new MyProcessor()) + .to("mock:result"); +----------------------------------------------------------- + +By default the *onCompletion* will be triggered when the +link:exchange.html[Exchange] is complete and regardless if the +link:exchange.html[Exchange] completed with success or with an failure +(such as an Exception was thrown). You can limit the trigger to only +occur `onCompleteOnly` or by `onFailureOnly` as shown below: + +[source,java] +----------------------------------------------------------- +from("direct:start") + // here we qualify onCompletion to only invoke when the exchange failed (exception or FAULT body) + .onCompletion().onFailureOnly() + .to("log:sync") + .to("mock:sync") + // must use end to denote the end of the onCompletion route + .end() + // here the original route continues + .process(new MyProcessor()) + .to("mock:result"); +----------------------------------------------------------- + +You can identify if the link:exchange.html[Exchange] is an +*onCompletion* link:exchange.html[Exchange] as Camel will add the +property `Exchange.ON_COMPLETION` with a boolean value of `true` when it +spin offs the *onCompletion* link:exchange.html[Exchange]. + +[[OnCompletion-UsingonCompletionfromSpringDSL]] +Using onCompletion from Spring DSL +++++++++++++++++++++++++++++++++++ + +The onCompletion is defined like this with Spring DSL: + +[source,xml] +----------------------------------------------------------- +<route> + <from uri="direct:start"/> + <!-- this onCompletion block will only be executed when the exchange is done being routed --> + <!-- this callback is always triggered even if the exchange failed --> + <onCompletion> + <!-- so this is a kinda like an after completion callback --> + <to uri="log:sync"/> + <to uri="mock:sync"/> + </onCompletion> + <process ref="myProcessor"/> + <to uri="mock:result"/> +</route> +----------------------------------------------------------- + +And the `onCompleteOnly` and `onFailureOnly` is defined as a boolean +attribute on the <onCompletion> tag so the failure example would be: + +[source,xml] +----------------------------------------------------------- +<route> + <from uri="direct:start"/> + <!-- this onCompletion block will only be executed when the exchange is done being routed --> + <!-- this callback is only triggered when the exchange failed, as we have onFailure=true --> + <onCompletion onFailureOnly="true"> + <to uri="log:sync"/> + <to uri="mock:sync"/> + </onCompletion> + <process ref="myProcessor"/> + <to uri="mock:result"/> +</route> +----------------------------------------------------------- + +[[OnCompletion-onCompletionwithglobalscope]] +onCompletion with global scope +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This works just like the route scope except from the fact that they are +defined globally. An example below: + +[source,java] +----------------------------------------------------------- +// define a global on completion that is invoked when the exchange is complete +onCompletion().to("log:global").to("mock:sync"); + +from("direct:start") + .process(new MyProcessor()) + .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: + +[source,xml] +----------------------------------------------------------- +<!-- this is a global onCompletion route that is invoke when any exchange is complete + as a kind of after callback --> +<onCompletion> + <to uri="log:global"/> + <to uri="mock:sync"/> +</onCompletion> + +<route> + <from uri="direct:start"/> + <process ref="myProcessor"/> + <to uri="mock:result"/> +</route> +----------------------------------------------------------- + + +*Route scope override Global scope* +If an *onCompletion* is defined in a route, it overrides *all* global +scoped and thus its only the route scoped that are used. The globally +scoped ones are never used. + +[[OnCompletion-UsingonCompletionwithonWhenpredicate]] +Using onCompletion with onWhen predicate +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As other DSL in Camel you can attach a link:predicate.html[Predicate] to +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: + +[source,java] +----------------------------------------------------------- +from("direct:start") + .onCompletion().onWhen(body().contains("Hello")) + // this route is only invoked when the original route is complete as a kind + // of completion callback. And also only if the onWhen predicate is true + .to("log:sync") + .to("mock:sync") + // must use end to denote the end of the onCompletion route + .end() + // here the original route contiues + .to("log:original") + .to("mock:result"); +----------------------------------------------------------- + +[[OnCompletion-UsingonCompletionwithorwithoutthreadpool]] +Using onCompletion with or without thread pool +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.14* + +OnCompletion will from Camel 2.14 onwards not use thread pool by +default. To use thread pool then either set a `executorService` or set +`parallelProcessing` to true. + +For example in Java DSL do + +[source,java] +----------------------------------------------------------- + onCompletion().parallelProcessing() + .to("mock:before") + .delay(1000) + .setBody(simple("OnComplete:${body}")); +----------------------------------------------------------- + +And in XML DSL + +[source,java] +-------------------------------------------------------------- + <onCompletion parallelProcessing="true"> + <to uri="before"/> + <delay><constant>1000</constant></delay> + <setBody><simple>OnComplete:${body}</simple></setBody> + </onCompletion> +-------------------------------------------------------------- + +You can also refer to a specific link:threading-model.html[thread pool] +to be used, using the executorServiceRef option + +[source,java] +-------------------------------------------------------------- + <onCompletion executorServiceRef="myThreadPool"> + <to uri="before"/> + <delay><constant>1000</constant></delay> + <setBody><simple>OnComplete:${body}</simple></setBody> + </onCompletion> +-------------------------------------------------------------- + + + +[[OnCompletion-UsingonCompletiontorunbeforerouteconsumersendsbackresponsetocallee]] +Using onCompletion to run before route consumer sends back response to callee +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.14* + +OnCompletion supports two modes + +* AfterConsumer - Default mode which runs after the consumer is done +* BeforeConsumer - Runs before the consumer is done, and before the +consumer writes back response to the callee + +The AfterConsumer mode is the default mode which is the same behavior as +in older Camel releases. + +The new BeforeConsumer mode is used to run onCompletion before the +consumer writes its response back to the callee (if in InOut mode). This +allows the onCompletion to modify the Exchange, such as adding special +headers, or to log the Exchange as a response logger etc. + +For example to always add a "created by" header you +use `modeBeforeConsumer()` as shown below: + +[source,java] +---------------------------------------------------- + .onCompletion().modeBeforeConsumer() + .setHeader("createdBy", constant("Someone")) + .end() +---------------------------------------------------- + + + +And in XML DSL you set the mode attribute to BeforeConsumer: + +[source,java] +------------------------------------------ + <onCompletion mode="BeforeConsumer"> + <setHeader headerName="createdBy"> + <constant>Someone</constant> + </setHeader> + </onCompletion> +------------------------------------------ + + + +[[OnCompletion-SeeAlso]] +See Also +^^^^^^^^ + +* Unit of Work +
