| [[Intercept-Intercept]] |
| Intercept |
| ~~~~~~~~~ |
| |
| The intercept feature in Camel supports intercepting |
| Exchanges while they are _on route_. + |
| We have overhauled the 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 Exchange in the route. |
| * `interceptFrom` that intercepts incoming Exchange |
| in the route. |
| * `interceptSendToEndpoint` that intercepts when an |
| Exchange is about to be sent to the given |
| Endpoint. |
| |
| These interceptors supports the following features: |
| |
| * Predicate using `when` to only trigger the |
| interceptor in certain conditions |
| * `stop` forces to stop continue routing the |
| Exchange and mark it as completed successful. Camel |
| will by default *not stop*. |
| * `skip` when used with `interceptSendToEndpoint` will *skip* sending |
| the 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 |
| 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 Exchange. You can for instance do this from |
| regular Java code in a POJO or |
| Processor. |
| |
| [[Intercept-Intercept.1]] |
| Intercept |
| ^^^^^^^^^ |
| |
| `Intercept` is like a regular interceptor that is applied on each |
| processing step the 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 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 Exchange twice. |
| |
| The `when` predicate is also support on the `intercept` so we can attach |
| a 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 |
| Exchange, in any route (it intercepts all the `from` |
| DSLs). This allows you to do some custom behavior for received |
| Exchanges. You can provide a specific uri for a |
| given 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 |
| <<log-component,Log>> component. As `proceed` is default then the |
| Exchange will continue its route, and thus it will |
| continue to `mock:first`. |
| |
| You can also attach a 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 |
| 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 |
| Exchange is being sent to the intercepted endpoint. |
| This allows you to route the Exchange to a |
| Detour or do some custom processing before the |
| 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` Predicate so we only intercept if |
| the 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 |
| Exchange is being sent to `mock:foo`: |
| |
| And this time we add the 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 <<simple-language,Simple>> |
| language for the 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 |
| 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 |
| Endpoint then the `interceptFrom` is not triggered. |
| |
| [[Intercept-SeeAlso]] |
| See Also |
| ^^^^^^^^ |
| |
| * link:architecture.adoc[Architecture] |
| |
| |