Forget the intercept.adoc file
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/43b79bca Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/43b79bca Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/43b79bca Branch: refs/heads/master Commit: 43b79bca26c27265b40e5c00e4625118c250c327 Parents: 7a7a55c Author: Andrea Cosentino <[email protected]> Authored: Mon May 23 16:57:31 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Mon May 23 16:57:31 2016 +0200 ---------------------------------------------------------------------- docs/user-manual/en/intercept.adoc | 274 ++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/43b79bca/docs/user-manual/en/intercept.adoc ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/intercept.adoc b/docs/user-manual/en/intercept.adoc new file mode 100644 index 0000000..e980acf --- /dev/null +++ b/docs/user-manual/en/intercept.adoc @@ -0,0 +1,274 @@ +[[Intercept-Intercept]] +Intercept +~~~~~~~~~ + +The intercept feature in Camel supports intercepting +link:exchange.html[Exchange]s while they are _on route_. + + We have overhauled the link:intercept.html[Intercept] in Camel 2.0 so +the following information is based on Camel 2.0. + +Camel supports three kinds of interceptors: + +* `intercept` that intercepts each and every processing step while +routing an link:exchange.html[Exchange] in the route. +* `interceptFrom` that intercepts incoming link:exchange.html[Exchange] +in the route. +* `interceptSendToEndpoint` that intercepts when an +link:exchange.html[Exchange] is about to be sent to the given +link:endpoint.html[Endpoint]. + +These interceptors supports the following features: + +* link:predicate.html[Predicate] using `when` to only trigger the +interceptor in certain conditions +* `stop` forces to stop continue routing the +link:exchange.html[Exchange] and mark it as completed successful. Camel +will by default *not stop*. +* `skip` when used with `interceptSendToEndpoint` will *skip* sending +the link:exchange.html[Exchange] to the original intended endpoint. +Camel will by default *not skip*. +* `interceptFrom` and `interceptSendToEndpoint` supports endpoint URI +matching by: exact uri, wildcard, regular expression. See advanced +section. +* The intercepted endpoint uri is stored as message header +`Exchange.INTERCEPTED_ENDPOINT`. + +`stop` can be used in general, it does not have to be used with an +link:intercept.html[Intercept] you can use it in regular routing as +well. + +You can also instruct Camel to `stop` continue routing your message if +you set the `Exchange.ROUTE_STOP` property to `"true"` or `Boolean.TRUE` +on the link:exchange.html[Exchange]. You can for instance do this from +regular Java code in a link:pojo.html[POJO] or +link:processor.html[Processor]. + +[[Intercept-Intercept.1]] +Intercept +^^^^^^^^^ + +`Intercept` is like a regular interceptor that is applied on each +processing step the link:exchange.html[Exchange] undergo while its being +routed. You can think of it as a _AOP before_ that is applied at each +DSL keyword you have defined in your route. + +The classic Hello World example would be: + +[source,java] +------------------------------------------------------------------------- +intercept().to("log:hello"); + +from("jms:queue:order").to("bean:validateOrder").to("bean:processOrder"); +------------------------------------------------------------------------- + +What happens is that the link:exchange.html[Exchange] is intercepted +before each processing step, that means that it will be intercepted +before + +* `.to("bean:validateOrder")` +* `.to("bean:processOrder")` + +So in this sample we intercept the link:exchange.html[Exchange] twice. + +The `when` predicate is also support on the `intercept` so we can attach +a link:predicate.html[Predicate] to only trigger the interception under +certain conditions. + + For instance in the sample below we only intercept if the message body +contains the string word *Hello*: + +And in the route below we want to stop in certain conditions, when the +message contains the word 'Hello': + +[[Intercept-UsingfromSpringDSL]] +Using from Spring DSL ++++++++++++++++++++++ + +The same hello world sample in Spring DSL would be: + +[source,xml] +-------------------------------------- +<camelContext ...> + <intercept> + <to uri="log:hello"/> + </intercept> + + <route> + <from uri="jms:queue:order"/> + <to uri="bean:validateOrder"/> + <to uri="bean:handleOrder"/> + </route> +</camelContext> +-------------------------------------- + +And the sample for using the *when* predicate would be: + +And the sample for using the *when* and *stop* would be: + +[[Intercept-InterceptFrom]] +InterceptFrom +^^^^^^^^^^^^^ + +`InterceptFrom` is for intercepting any incoming +link:exchange.html[Exchange], in any route (it intercepts all the `from` +DSLs). This allows you to do some custom behavior for received +link:exchange.html[Exchange]s. You can provide a specific uri for a +given link:endpoint.html[Endpoint] then it only applies for that +particular route. + +So lets start with the logging example. We want to log all the +*incoming* requests so we use `interceptFrom` to route to the +link:log.html[Log] component. As `proceed` is default then the +link:exchange.html[Exchange] will continue its route, and thus it will +continue to `mock:first`. + +You can also attach a link:predicate.html[Predicate] to only trigger if +certain conditions is meet. For instance in the route below we intercept +when a test message is send to us, so we can do some custom processing +before we continue routing: + +And if we want to filter out certain messages we can use the `stop()` to +instruct Camel to stop continue routing the +link:exchange.html[Exchange]: + +And if want to only apply a specific endpoint, as the *seda:bar* +endpoint in the sample below, we can do it like this: + +[[Intercept-UsingfromSpringDSL.1]] +Using from Spring DSL ++++++++++++++++++++++ + +Intercept is of course also available using Spring DSL as shown in the +sample below: + +*Notice:* `stop` is also supported in `interceptFrom` so you can +intercept from certain endpoints and route then elsewhere and `stop` to +not continue routing in the original intended route path. + +[[Intercept-InterceptSendToEndpoint]] +InterceptSendToEndpoint +^^^^^^^^^^^^^^^^^^^^^^^ + +*Available as of Camel 2.0* + +Intercept send to endpoint is triggered when an +link:exchange.html[Exchange] is being sent to the intercepted endpoint. +This allows you to route the link:exchange.html[Exchange] to a +link:detour.html[Detour] or do some custom processing before the +link:exchange.html[Exchange] is sent to the original intended +destination. You can also skip sending to the intended destination. By +default Camel will send to the original intended destination after the +intercepted route completes. And as the regular intercept you can also +define an `when` link:predicate.html[Predicate] so we only intercept if +the link:predicate.html[Predicate] evaluates to *true*. This allows you +do do a bit of filtering, to only intercept when certain criteria is +meet. + +Let start with a simple example, where we want to intercept when an +link:exchange.html[Exchange] is being sent to `mock:foo`: + +And this time we add the link:predicate.html[Predicate] so its only when +the message body is `Hello World` we intercept. + +And to skip sending to the `mock:foo` endpoint we use the *`skip()` DSL +in the route at the end to instruct Camel to skip sending to the +original intended endpoint. + +*Conditional skipping* + +The combination of `skipSendToEndpoint` with a `when` predicate behaves +differently depending on the Camel version: + +* *Before Camel 2.10:* the skipping is applied unconditionally whether +the `when` predicate is matched or not, i.e. the `when` predicate only +determines whether the body of the interception will execute, but it +does not control skipping behaviour +* *As of Camel 2.10:* the skipping only occurs if the `when` predicate +is matched, leading to more natural logic altogether. + +[[Intercept-UsingfromSpringDSL.2]] +Using from Spring DSL ++++++++++++++++++++++ + +Intercept endpoint is of course also available using Spring DSL. + +We start with the first example from above in Spring DSL: + +And the 2nd. Notice how we can leverage the link:simple.html[Simple] +language for the link:predicate.html[Predicate]: + +And the 3rd with the `skip`, notice skip is set with the +`skipSendToOriginalEndpoint` attribute on the *interceptSendToEndpoint* +tag: + +[[Intercept-AdvancedusageofIntercpt]] +Advanced usage of Intercpt +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `interceptFrom` and `interceptSendToEndpoint` supports endpoint URI +matching by the following rules in the given order: + +* match by exact URI name. This is the sample we have seen above. +* match by wildcard +* match by regular expression. + +The real endpoint that was intercepted is stored as uri in the message +IN header with the key `Exchange.INTERCEPTED_ENDPOINT`. + + This allows you to get hold of this information, when you for instance +match by wildcard. Then you know the real endpoint that was intercepted +and can react accordingly. + +[[Intercept-Matchbywildcard]] +Match by wildcard ++++++++++++++++++ + +Match by wildcard allows you to match a range of endpoint or all of a +given type. For instance use `uri="file:*"` will match all +link:file2.html[File] based endpoints. + +[source,java] +------------------------------------- +intercept("jms:*").to("log:fromjms"); +------------------------------------- + +Wildcards is match that the text before the * is matched against the +given endpoint and if it also starts with the same characters its a +match. For instance you can do: + +[source,java] +---------------------------------------------------------- +intercept("file://order/inbox/*").to("log:newfileorders"); +---------------------------------------------------------- + +To intercept any files received from the `order/inbox` folder. + +[[Intercept-Matchbyregularexpression]] +Match by regular expression ++++++++++++++++++++++++++++ + +Match by regular expression is just like match by wildcard but using +regex instead. So if we want to intercept incoming messages from gold +and silver JMS queues we can do: + +[source,java] +----------------------------------------------------------- +intercept("jms:queue:(gold|silver)").to("seda:handleFast"); +----------------------------------------------------------- + +*About dynamic and static behavior of interceptFrom and +interceptSendToEndpoint* + +The `interceptSendToEndpoint` is dynamic hence it will also trigger if a +dynamic URI is constructed that Camel was not aware of at startup +time. + + The `interceptFrom` is not dynamic as it only intercepts input to +routes registered as routes in `CamelContext`. So if you dynamic +construct a `Consumer` using the Camel API and consumes an +link:endpoint.html[Endpoint] then the `interceptFrom` is not triggered. + +[[Intercept-SeeAlso]] +See Also +^^^^^^^^ + +* link:architecture.html[Architecture] +* link:aop.html[AOP] +
