Try ... Catch ... Finally camel

http://camel.apache.org/try-catch-finally.html

Try ... Catch ... Finally

Camel supports the Java equivalent of try .. catch and finally directly in the DSL.
It aims to work like its Java sisters but with more power. Especially in Camel 2.0 where we gave this feature an overhaul.

In Camel we prefix the keywords with do to avoid having same keyword as Java. So we have:

• doTry
• doCatch
• doFinally
• end to end the block in Java DSL

Notice this document is based on how it works in Camel 2.0. In Camel 1.x this feature isn't as powerful and it uses a slight different keyword names.

Camel error handling is disabled
When using doTry .. doCatch .. doFinally then the regular Camel Error Handler does not apply. That means any onException or the likes does not trigger. The reason is thatdoTry .. doCatch .. doFinally is in fact its own error handler and that it aims to mimic and work like how try/catch/finally works in Java.

AboutdoCatch and its power over Java

The doCatch in Camel is empowered over its Java sister.

First of all you can define multiple exceptions to catch in a single block.

And second of all an important aspect over the regular Java counter parts is that Camel will check in the exception hierarchy when it matches a thrown exception against thedoCatch blocks. The reasons is that many times the original caused exceptions is wrapped by other wrapper exceptions, typically transposing the exception from a checked to a runtime exception.
Camel for instance does this by wrapped it in a CamelRuntimeException. So if the original caused exception is anjava.io.IOException then Camel will still match a doCatch block defined with anjava.io.IOException. And just like Java the order in which you have multipledoCatch blocks matter. Camel will iterate from the top going down and use the firstdoCatch that matches the exception. The reason is to keep it similar to the regular java and how it selects a catch block. This differers from theException Clause that has a more intelligent exception selection strategy among multipleonException definitions, where it also consider the delta in the exception hierarchy to select the best definition.

A third feature is that you can attach a onWhen predicate to signal if the catch should trigger or not at runtime.

And to simulate rehrowing an exception from a doCatch you should use thehandled predicate. If its evaluated to false Camel will reattach the exception on theExchange.

Using try .. catch .. finally in Java DSL

In the route below we have all keywords in action. As the code is based on a unit test we route usingMock.

from("direct:start")    .doTry()        .process(new ProcessorFail())        .to("mock:result")    .doCatch(IOException.class, IllegalStateException.class)        .to("mock:catch")    .doFinally()        .to("mock:finally")    .end();

And in the route below we want to indicate if an IOException occured we want to route it elsewhere and at the same time keep the exception so the original caller is notified about this exception. To do this we need to notrethrow the exception and this is why we use handled and set it to false to indicate, no we did not handle it so please keep the exception.
The 2nd exception block can be omitted but as the code is based on an unit test we want to test the behavior nonIOException as well.

from("direct:start")    // here is our try where we try processing the exchange in the route below if it fails    // we can catch it below, just like regular try .. catch .. finally in Java    .doTry()        .process(new ProcessorFail())        .to("mock:result")    // catch IOExcption that we do not want to handle, eg the caller should get the error back    .doCatch(IOException.class)        // mark this as NOT handled, eg the caller will also get the exception        .handled(false)        .to("mock:io")    .doCatch(Exception.class)        // and catch all other exceptions        // they are handled by default (ie handled = true)        .to("mock:error")    // here the try block ends    .end();

And finally we have an example of the onWhen predicate in action. We can attach it to adoCatch block and at runtime determine if the block should be triggered or not.
In our case we only want to trigger if the caused exception message contains the damn word.

from("direct:start")    // here is our try where we try processing the exchange in the route below if it fails    // we can catch it below, just like regular try .. catch .. finally in Java    .doTry()        .process(new ProcessorFail())        .to("mock:result")    // here we catch the following 2 exceptions but only if    // the onWhen predicate matches, eg if the exception messsage    // conatins the string word Damn    .doCatch(IOException.class, IllegalStateException.class)        .onWhen(exceptionMessage().contains("Damn"))        .to("mock:catch")    // another catch for CamelExchangeException that does not have any onWhen predicate    .doCatch(CamelExchangeException.class)        .to("mock:catchCamel")    // and the finally that is always processed    .doFinally()        .to("mock:finally")    // here the try block ends    .end();

Using try .. catch .. finally in Spring DSL

We show the three sample samples using Spring DSL instead.

In the route below we have all keywords in action. As the code is based on a unit test we route usingMock.

<route>    <from uri="direct:start"/>    <!-- here the try starts. its a try .. catch .. finally just as regular java code -->    <doTry>        <process ref="processorFail"/>        <to uri="mock:result"/>        <doCatch>            <!-- catch multiple exceptions -->            <exception>java.io.IOException</exception>            <exception>java.lang.IllegalStateException</exception>            <to uri="mock:catch"/>        </doCatch>        <doFinally>            <to uri="mock:finally"/>        </doFinally>    </doTry></route>

And in the route below we want to indicate if an IOException occured we want to route it elsewhere and at the same time keep the exception so the original caller is notified about this exception. To do this we need to notrethrow the exception and this is why we use handled and set it to false to indicate, no we did not handle it so please keep the exception.
The 2nd exception block can be omitted but as the code is based on an unit test we want to test the behavior nonIOException as well.

<route>    <from uri="direct:start"/>    <!-- here the try starts. its a try .. catch .. finally just as regular java code -->    <doTry>        <process ref="processorFail"/>        <to uri="mock:result"/>        <doCatch>            <!-- catch IOExcption that we do not want to handle, eg the caller should get the error back -->            <exception>java.io.IOException</exception>            <!-- mark this as NOT handled, eg the caller will also get the exception -->            <handled>                <constant>false</constant>            </handled>            <to uri="mock:io"/>        </doCatch>        <doCatch>            <!-- and catch all other exceptions they are handled by default (ie handled = true) -->            <exception>java.lang.Exception</exception>            <to uri="mock:error"/>        </doCatch>    </doTry></route>

And finally we have an example of the onWhen predicate in action. We can attach it to adoCatch block and at runtime determine if the block should be triggered or not.
In our case we only want to trigger if the caused exception message contains the damn word.

<route>    <from uri="direct:start"/>    <!-- here the try starts. its a try .. catch .. finally just as regular java code -->    <doTry>        <process ref="processorFail"/>        <to uri="mock:result"/>        <!-- here we catch the below 2 kind of exceptions but ONLY if the onWhen predicate matches             that means that the exception message should contain the string word 'Damn' -->        <doCatch>            <exception>java.io.IOException</exception>            <exception>java.lang.IllegalStateException</exception>            <onWhen>                <simple>${exception.message} contains 'Damn'</simple>            </onWhen>            <to uri="mock:catch"/>        </doCatch>        <!-- we can have multiple catch blocks for different exception and with their own onWhen -->        <doCatch>            <exception>org.apache.camel.CamelExchangeException</exception>            <to uri="mock:catchCamel"/>        </doCatch>        <!-- the finally is always processed -->        <doFinally>            <to uri="mock:finally"/>        </doFinally>    </doTry></route>