camel Intercept

http://camel.apache.org/intercept.html

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 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:

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:

intercept().when(body().contains("Hello")).to("mock:intercepted");

from("direct:start")
    .to("mock:foo", "mock:bar", "mock:result");

And in the route below we want to stop in certain conditions, when the message contains the word 'Hello':

intercept().when(body().contains("Hello")).to("mock:intercepted").stop();

from("direct:start")
    .to("mock:foo", "mock:bar", "mock:result");

Using from Spring DSL

The same hello world sample in Spring DSL would be:

<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:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <!-- here we intercept each processing step in the routing and do a detour
         routing where we route the exhange to the mock:intercepted endpoint.
         We have applied a when predicate so the interceptor only applies
         if the message body contains the string word 'Hello' -->
    <intercept>
        <when>
            <simple>${in.body} contains 'Hello'</simple>
        </when>
        <to uri="mock:intercepted"/>
    </intercept>

    <!-- here we have a very simple route -->
    <route>
        <from uri="direct:start"/>
        <to uri="mock:foo"/>
        <to uri="mock:bar"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

And the sample for using the when and stop would be:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <intercept>
        <!-- only trigger this interceptor if the message body contains the word Hello -->
        <when>
            <simple>${in.body} contains 'Hello'</simple>
        </when>
        <to uri="mock:intercepted"/>
        <!-- stop continue routing -->
        <stop/>
    </intercept>

    <!-- here we have a very simple route -->
    <route>
        <from uri="direct:start"/>
        <to uri="mock:foo"/>
        <to uri="mock:bar"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

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. As proceed is default then the Exchange will continue its route, and thus it will continue to mock:first.

// intercept all incomming routes and log it
interceptFrom().to("log:received");

// and here we have a couple of routes
from("direct:start").to("mock:first").to("seda:bar");

from("seda:bar").to("mock:result");

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:

interceptFrom()
    .when(header("usertype").isEqualTo("test"))
    .process(new MyTestServiceProcessor())
    .to("mock:intercepted");

// and here is our route
from("direct:start").to("seda:bar").to("mock:result");

And if we want to filter out certain messages we can use the stop() to instruct Camel to stop continue routing the Exchange:

interceptFrom()
    .when(header("usertype").isEqualTo("test"))
    // here we use stop() to tell Camel to NOT continue routing the message.
    // this let us act as a filter, to drop certain messages.
    .stop();

// and here is our route
from("direct:start").to("seda:bar").to("mock:result");

And if want to only apply a specific endpoint, as the seda:bar endpoint in the sample below, we can do it like this:

// only trigger when incoming from seda:bar endpoint
interceptFrom("seda:bar").to("mock:bar");

// and here we have a couple of routes
from("direct:start").to("mock:first").to("seda:bar");

from("seda:bar").to("mock:result");

from("seda:foo").to("mock:result");

Using from Spring DSL

Intercept is of course also available using Spring DSL as shown in the sample below:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <!-- intercept incoming messages and route them to the mock:middle1 endpoint
         before we proceed and continue routing from the point of interceptions, that
         is mock:end will be the next target -->
    <interceptFrom>
        <to uri="mock:middle1"/>
    </interceptFrom>

    <!-- here we have a very simple route -->
    <route>
        <from uri="direct:start"/>
        <to uri="mock:end"/>
    </route>
</camelContext>

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.

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:

// we intercept by endpoint, that means that whenever an exchange is about to be sent to
// this endpoint, its intercepted and routed with this detour route beforehand
// afterwards its send to the original intended destination. So this is kinda AOP before.
// That means mock:foo will receive the message (Bye World).
interceptSendToEndpoint("mock:foo")
    .to("mock:detour").transform(constant("Bye World"));

from("direct:first")
    .to("mock:bar")
    .to("mock:foo")
    .to("mock:result");

And this time we add the Predicate so its only when the message body is Hello World we intercept.

// we can also attach a predicate to the endpoint interceptor. So in this example the exchange is
// only intercepted if the body is Hello World
interceptSendToEndpoint("mock:foo").when(body().isEqualTo("Hello World"))
    .to("mock:detour").transform(constant("Bye World"));

from("direct:second")
    .to("mock:bar")
    .to("mock:foo")
    .to("mock:result");

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.

// since we use the skipSendToOriginalEndpoint() we instruct Camel to skip
// sending the exchange to the original intended destination after the intercept
// route is complete.
// That means that mock:foo will NOT receive the message, but the message
// is skipped and continued in the original route, so mock:result will receive
// the message.
interceptSendToEndpoint("mock:foo").skipSendToOriginalEndpoint()
    .transform(constant("Bye World")).to("mock:detour");

from("direct:third")
    .to("mock:bar")
    .to("mock:foo")
    .to("mock:result");

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.

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:

<camelContext xmlns="http://camel.apache.org/schema/spring">

    <!-- we intercept by endpoint, that means that whenever an exchange is about to be sent to
         this endpoint, its intercepted and routed with this detour route beforehand
         afterwards its send to the original intended destination. So this is kinda AOP before.
         That means mock:foo will receive the message (Bye World). -->
    <interceptSendToEndpoint uri="mock:foo">
        <to uri="mock:detour"/>
        <transform>
            <constant>Bye World</constant>
        </transform>
    </interceptSendToEndpoint>

    <route>
        <from uri="direct:first"/>
        <to uri="mock:bar"/>
        <to uri="mock:foo"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

And the 2nd. Notice how we can leverage the Simple language for the Predicate:

<camelContext xmlns="http://camel.apache.org/schema/spring">

    <interceptSendToEndpoint uri="mock:foo">
        <when><simple>${body} == 'Hello World'</simple></when>
        <to uri="mock:detour"/>
        <transform>
            <constant>Bye World</constant>
        </transform>
    </interceptSendToEndpoint>

    <route>
        <from uri="direct:second"/>
        <to uri="mock:bar"/>
        <to uri="mock:foo"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

And the 3rd with the skip, notice skip is set with the skipSendToOriginalEndpoint attribute on the interceptSendToEndpoint tag:

<camelContext xmlns="http://camel.apache.org/schema/spring">

    <!-- since we set the skipSendToOriginalEndpoint attribute to true we instruct
         Camel to skip sending the exchange to the original intended destination.
         That means that mock:foo will NOT receive the message, but the message
         is skipped and continued in the original route, so mock:result will receive
         the message. -->
    <interceptSendToEndpoint uri="mock:foo" skipSendToOriginalEndpoint="true">
        <transform>
            <constant>Bye World</constant>
        </transform>
        <to uri="mock:detour"/>
    </interceptSendToEndpoint>

    <route>
        <from uri="direct:third"/>
        <to uri="mock:bar"/>
        <to uri="mock:foo"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

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.

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.

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:

intercept("file://order/inbox/*").to("log:newfileorders");

To intercept any files received from the order/inbox folder.

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:

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