2009-04-20

On the road to Camel 2.0 - Try Catch Finally

Today I have just completed an overhaul of the try catch finally DSLs we have in Apache Camel.

And since I improved (hmm added) the documentation to the Apache Camel wiki I might as well do a blog about it as well :)

Using try catch finally in Apache Camel
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 (Spring DSL have the </doTry> tag to end)
About doCatch 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 secondly you can attach a onWhen predicate to signal if the catch should trigger or not at runtime.

To simulate rehrowing an exception from a doCatch you should use the handled predicate. If its evaluated to false Camel will reattach the exception on the Exchange.

And just like Java the order in which you have multiple doCatch blocks matter. Camel will iterate from the top going down and use the first doCatch that matches the exception and if the onWhen predicate matches as well (if any provided). This is the same behavior as the Exception Clause.

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 using Mock.

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

And here we have the same route in Spring DSL:
<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>

There are more samples in the Camel Try Catch Finally documentation that also demonstrates the onWhen and handled predicates and what they are used for.

The overhaul was needed as it really brings the power of using try .. catch .. finally up to the same level as the exception clauses and error handlers in Camel. But having them right at your fingertips as regular Java like try .. catch .. finally brings the gaps from thinking Java to EIP patterns a bit closer.

PS: Mind that the static wiki documentation takes a few hours to be updated based on the dynamic changes I recently added, so some of the links might not work until then. 

6 comments:

springhill @ blogspot said...

good work, and when to release GA?

Claus Ibsen said...

We have a discussion on the Camel dev list:
http://www.nabble.com/-DISCUSS--Release-Camel-2.0-M2-and-1.6.1-td23160465.html

What we want to do is to release a 2nd milestone in next week.

Then thereafter we should be on the road for a RC and thus also GA. We aim to have GA before summer 2009.

Roger Searjeant said...

Hi Claus,
I've downloaded/installed 2.0M1 but the new doTry/doCatch etc. don't appear to be part of this release. I am particularly keen to use the new 'handled' feature to pass exceptions through to handlers. The new keywords don't appear to be in this release, though the online docs suggest that they are.

I have checked that I'm referencing the right jars. I've been browsing the 2.0 source and can't see the 'doTry' etc. stuff anywhere.

Am I missing something, or is this all slated for M2 / later?

Cheers,
Roger

Claus Ibsen said...

Roger,

The overhaul was done after M1 so they will appear in M2.

You can try the SNAPSHOTS if you like. Details at the Apache Camel downloads page with details of the maven repo.

PARAS MUKADAM said...

Thanks for your contribution to this wonderful project. It rocks and is rock solid!

Claus Ibsen said...

Paras

Thanks for the kind words. We appreciate any kind of feedback on Apache Camel. Glad you enjoy using Camel.